{
  "openapi": "3.1.0",
  "info": {
    "title": "Clemta Partner API",
    "description": "The Clemta partner surface. Authenticate with your API key as a bearer\ntoken (`Authorization: Bearer clmt_live_` or `clmt_test_`). Keys with\nthe `clmt_test_` prefix operate in sandbox mode (`livemode: false`): test\ndata never reaches fulfillment or billing.\n\nVersioning is date-based: pass `Clemta-Version` to pin a\nversion, omit it to run on your account's pinned default. The effective\nversion is echoed back on every response.\n",
    "version": "2026-08-13"
  },
  "servers": [
    {
      "url": "https://api.clemta.com/v1",
      "description": "Single host for both modes: `clmt_test_` keys operate in sandbox mode, `clmt_live_` keys in live mode.\n"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Identity",
      "description": "Identify the calling API key."
    },
    {
      "name": "Accounts",
      "description": "Create and read customer accounts - the incorporators companies are created under."
    },
    {
      "name": "Companies",
      "description": "Create and read customer companies."
    },
    {
      "name": "Service orders",
      "description": "Order services against a company and follow their fulfilment."
    },
    {
      "name": "Products",
      "description": "The catalog you can offer, at your partner prices."
    },
    {
      "name": "Tax filings",
      "description": "Federal and state tax filings on your companies, opened by your customer against the company's entitlements and worked by Clemta. Read-only. Follow them with the tax_filing.* events."
    },
    {
      "name": "Files",
      "description": "Documents Clemta publishes on your companies - formation deliverables, filed forms, letters. Read-only. Customer KYC uploads are write-only and never listed."
    },
    {
      "name": "Requirements",
      "description": "Everything needed from you or your customer - identity documents, service-order forms, Clemta's asks - as one resolvable resource. Fulfill over the API or hand your customer a hosted link."
    },
    {
      "name": "Status tracking",
      "description": "End-customer status links - keyless, read-only access to a company's live status."
    },
    {
      "name": "Events",
      "description": "Poll the partner event stream."
    },
    {
      "name": "Webhooks",
      "description": "Events we deliver to your endpoint, and how to verify them. Each webhook below is a request WE send to you. Respond 2xx to acknowledge. Deliveries are signed and retried up to 20 times with exponential backoff, from 15 seconds up to 6 hours apart, until acknowledged. Answer `410 Gone` to have the endpoint disabled and deliveries stopped. A `Retry-After` header on a `429` or `503` pushes the next attempt back. An endpoint that fails continuously for three days is disabled automatically and the workspace owner is emailed - no events are lost, the stream stays available on `GET /v1/events`.\n\n## Delivery semantics\n\nDelivery is at-least-once, so the same event can reach you more than once. Deduplicate on `Clemta-Webhook-Id` and process each event once.\n\nOrdering is best-effort, not a guarantee. Events for one endpoint are normally delivered in the order they occurred, but a delivery that keeps failing can let later events arrive ahead of it, and a retry can land out of order. Do not depend on receive order - use the event `timestamp` field when sequence matters, and treat each event as self-contained (fetch any related resource you need rather than assuming an earlier event arrived first).\n\nNothing is lost while your endpoint is down. Every event stays on `GET /v1/events` with no expiry, filterable by `created_at` and `company_id`, so you can reconcile anything a delivery missed - this is the source of truth, webhooks are the fast path to it.\n\n## Verifying a delivery\n\nDeliveries are signed per the [Standard Webhooks](https://www.standardwebhooks.com) specification, carrying BOTH schemes in one header: a symmetric `v1` HMAC (verify with your endpoint secret and any standardwebhooks library) and an asymmetric `v1a` ed25519 signature (verify with the endpoint's public key, no shared secret held). Use whichever suits your setup.\n\nEvery endpoint has its OWN signing secret (`whsec_...`), shown once when you create the endpoint. Each delivery carries three headers:\n\n- `Clemta-Webhook-Id` - the event id. Stable across retries: use it as an idempotency key so a redelivered event is processed once.\n- `Clemta-Webhook-Timestamp` - unix seconds of THIS attempt (a retry carries a fresh one).\n- `Clemta-Webhook-Signature` - a space-delimited list of signatures, each prefixed with its scheme: `v1,\u003cbase64\u003e` (HMAC) and `v1a,\u003cbase64\u003e` (ed25519). More than one `v1` entry while a secret rotation's overlap window is open, one per active secret.\n\nEach is also sent under its bare Standard Webhooks name (`webhook-id`, `webhook-timestamp`, `webhook-signature`) with the same value, which is what off-the-shelf standardwebhooks libraries look up.\n\nTo verify by hand:\n\n1. Build the signed content by joining the id, the timestamp, and the raw request body with literal `.` separators: `{id}.{timestamp}.{body}`. Use the body exactly as received - do not re-serialize the JSON.\n2. Base64-decode your endpoint secret after the `whsec_` prefix. That is the HMAC key.\n3. Compute HMAC-SHA256 over the signed content, base64 encode it, and compare it against each `v1,` entry in constant time. Accept if any matches, otherwise reject.\n4. Check the timestamp is within 5 minutes of now, to reject replays.\n\nBecause the secret is unique to your endpoint, a signature can only be verified by you - a delivery meant for another endpoint cannot be made to verify here. Keep the secret confidential. If it leaks, roll the endpoint's secret from the Webhooks page of your partner dashboard."
    },
    {
      "name": "Sandbox",
      "description": "Test-key-only endpoints for rehearsing event flows. Trigger a lifecycle transition on a test company and receive the matching webhook, without waiting for a real formation to progress."
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "tags": [
          "Identity"
        ],
        "operationId": "getMe",
        "summary": "Identify the calling API key",
        "description": "Returns the partner and mode the presented key resolves to.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's identity.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/accounts": {
      "post": {
        "tags": [
          "Accounts"
        ],
        "operationId": "createAccount",
        "summary": "Create an account for a customer",
        "description": "Creates an account - one of your end customers - that companies are then created under. The customer receives no messages from Clemta. Pass `Idempotency-Key` to make retries safe.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAccountBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created account.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Accounts"
        ],
        "operationId": "listAccounts",
        "summary": "List your accounts - sortable, cursor-paged",
        "parameters": [
          {
            "$ref": "#/components/parameters/Sort"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/After"
          },
          {
            "$ref": "#/components/parameters/Before"
          }
        ],
        "responses": {
          "200": {
            "description": "One page of accounts, newest first by default.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "description": "Your accounts, newest first. Sortable by `created_at`."
      }
    },
    "/accounts/{accountID}": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "operationId": "getAccount",
        "summary": "Fetch an account",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The account.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Accounts"
        ],
        "operationId": "updateAccount",
        "summary": "Update an account's metadata",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAccountBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated account.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies": {
      "post": {
        "tags": [
          "Companies"
        ],
        "operationId": "createCompany",
        "summary": "Create a customer company",
        "description": "Creates a customer and a company shell attributed to you. The customer receives no messages from Clemta. Pass `Idempotency-Key` to make retries safe.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          },
          {
            "$ref": "#/components/parameters/ClemtaAccount"
          },
          {
            "$ref": "#/components/parameters/ExpandCompany"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCompanyBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created company.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "listCompanies",
        "summary": "List your companies - filterable, sortable, cursor-paged",
        "parameters": [
          {
            "$ref": "#/components/parameters/Status"
          },
          {
            "$ref": "#/components/parameters/AccountIdFilter"
          },
          {
            "$ref": "#/components/parameters/ExpandCompany"
          },
          {
            "$ref": "#/components/parameters/Sort"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/After"
          },
          {
            "$ref": "#/components/parameters/Before"
          }
        ],
        "responses": {
          "200": {
            "description": "One page of companies, newest first by default.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "description": "Sort by `created_at` or `name`. Filter by any company field, `external_id` and `state` included."
      }
    },
    "/companies/{companyID}": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getCompany",
        "summary": "Retrieve a company",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          },
          {
            "$ref": "#/components/parameters/ExpandCompany"
          }
        ],
        "responses": {
          "200": {
            "description": "The company.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Companies"
        ],
        "operationId": "updateCompany",
        "summary": "Update a company",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCompanyBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated company.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{companyID}/service-orders": {
      "post": {
        "tags": [
          "Service orders"
        ],
        "operationId": "createServiceOrder",
        "summary": "Attach a service to a company",
        "description": "Orders a product against the company and bills you for it at creation, at your partner price. Idempotent - re-attaching the same product returns the existing order and does not bill you twice. Pass `Idempotency-Key` for safe retries.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateServiceOrderBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The service order.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceOrder"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Service orders"
        ],
        "operationId": "listServiceOrders",
        "summary": "List a company's service orders",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ExpandServiceOrder"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The company's service orders, newest first.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceOrderList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{companyID}/service-orders/{orderID}": {
      "get": {
        "tags": [
          "Service orders"
        ],
        "operationId": "getServiceOrder",
        "summary": "Retrieve a service order",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ServiceOrderId"
          },
          {
            "$ref": "#/components/parameters/ExpandServiceOrder"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The service order.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceOrder"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Service orders"
        ],
        "operationId": "updateServiceOrder",
        "summary": "Upgrade a service order's options",
        "description": "Changes an in-flight order's variant choices and bills you the price DIFFERENCE - for example moving an `ein` order's `processing` from `standard` to `expedited` after the fact. Only upgrades are accepted (the new choice must not price below the current one), the order must not be completed or canceled, and the product's `available_when` must still hold for the company as it stands now - an ein upgrade is refused once the company's EIN is recorded. One upgrade may stand at a time. Choices that add a companion service attach it automatically.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ServiceOrderId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateServiceOrderBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The upgraded service order, at its new price.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceOrder"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Service orders"
        ],
        "operationId": "cancelServiceOrder",
        "summary": "Cancel a service order",
        "description": "Cancels an order still in `received` and credits back what you were billed. An order already in fulfilment cannot be reversed, but an ACTIVE RECURRING one takes a cancellation REQUEST instead: the call stamps `renewal_cancel_requested_at` and Clemta decides. Renewals keep billing until the request is approved. On approval the service runs to the end of the current period (`renewal_ends_at`) and is not billed again - except a product billed in arrears, whose running period still bills at its end, since it was served. You hear the outcome as `service_order.renewal_canceled` or `service_order.renewal_cancel_denied`. Fulfilment status is untouched. Cancelling again while a request is pending or decided is a no-op. A one-time order in fulfilment is refused with 409.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ServiceOrderId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The cancelled service order.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceOrder"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "operationId": "listProducts",
        "summary": "List the products you can offer, at your prices",
        "description": "Your catalog with your partner price on each line - your override where you have one, the default otherwise. These keys are what you pass as `product_key` when you attach a service order.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "Your catalog.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/products/{productKey}/price-preview": {
      "get": {
        "tags": [
          "Products"
        ],
        "operationId": "previewProductPrice",
        "summary": "Preview every line an order would bill",
        "description": "Resolve one product for a company profile BEFORE creating anything: your own amount (override, matching price rule, or default - `applied_rule` says which), each option value's effective amount, and every pass-through government or state fee line at today's amounts. Use it to price your own offer with no surprises. The order itself resolves again and freezes what it billed on the order's `fees`. Formation keys also carry the state's filing fee.",
        "parameters": [
          {
            "name": "productKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "annual_state_filing"
          },
          {
            "name": "entity_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "llc",
                "c_corp"
              ]
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            },
            "description": "The company's formation state, as a 2-letter code.",
            "example": "DE"
          },
          {
            "name": "pre_existing",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Preview for a pre-existing company you bring in. Defaults to false."
          },
          {
            "name": "owners_count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            },
            "description": "How many owners the company has. Defaults to 1."
          },
          {
            "name": "has_ein",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Whether the company already holds an EIN. A price rule may condition on it, so state it to preview the same amount the order resolves. Defaults to false (a fresh formation)."
          },
          {
            "name": "incorporated",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Whether the company is already incorporated (holds a formation date). A price rule may condition on it. Defaults to false."
          }
        ],
        "responses": {
          "200": {
            "description": "The resolved preview.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricePreview"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/companies/price-preview": {
      "post": {
        "tags": [
          "Companies"
        ],
        "operationId": "previewCompanyBasket",
        "summary": "Preview what creating a company would bill",
        "description": "Resolve the whole basket a company create would charge - the formation with its state filing fee, every mandatory service the profile auto-attaches, and every service you list - WITHOUT creating anything. Priced by the same resolution the create runs, so it cannot quote a total the create does not charge. Each line carries its own interval, and the lines are not summed. Amounts are estimates - the create resolves again and freezes what it billed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyPricePreviewBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The resolved basket.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyPricePreview"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/companies/{companyID}/products/{productKey}/price-preview": {
      "get": {
        "tags": [
          "Products"
        ],
        "operationId": "previewCompanyProductPrice",
        "summary": "Preview a product's price for an existing company",
        "description": "Resolve what a product would bill for THIS company, read from the company's own attributes - no profile query params to state or get wrong. It resolves against the same facts the order does (entity type, state, owner count, whether it holds an EIN, whether it is incorporated), so it cannot quote a price the order would not charge. Returns your own amount (override, matching price rule, or default - `applied_rule` says which), each option value's effective amount, and every pass-through government or state fee line at today's amounts. Use `GET /products/{productKey}/price-preview` instead to price a product for a hypothetical company before one exists.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "name": "productKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "annual_state_filing"
          }
        ],
        "responses": {
          "200": {
            "description": "The resolved preview for this company.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricePreview"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/companies/{companyID}/status-tokens": {
      "post": {
        "tags": [
          "Status tracking"
        ],
        "operationId": "createStatusToken",
        "summary": "Create an end-customer status link",
        "description": "Mints a read-only status link for the company and returns its URL. Hand the URL to your customer. Anyone holding it can read the company's live status - progress only, no documents, no personal data, no prices - by calling GET /status/{token}, so you can drive a progress view in your own product without sharing your API key. Multiple links per company are allowed, each individually revocable. The URL is shown once.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "201": {
            "description": "The status link, with its URL shown once.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusToken"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Status tracking"
        ],
        "operationId": "listStatusTokens",
        "summary": "List a company's status links",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The company's status links. The URLs are not returned again.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusTokenList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{companyID}/status-tokens/{tokenID}": {
      "delete": {
        "tags": [
          "Status tracking"
        ],
        "operationId": "revokeStatusToken",
        "summary": "Revoke a status link",
        "description": "Kills the link everywhere within seconds.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/StatusTokenId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "204": {
            "description": "The link was revoked."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/status/{token}": {
      "get": {
        "tags": [
          "Status tracking"
        ],
        "operationId": "getStatus",
        "summary": "Read a company's status by its link token",
        "description": "The end customer's read-only status, resolved from the status token in the path - no API key. Returns only progress as JSON: no documents, no personal data, no prices. Use it to drive a progress view in your own product.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "The raw status token from the link.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The company's live status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusView"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "operationId": "listEvents",
        "summary": "List your event stream - newest first, cursor-paged",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeFilter"
          },
          {
            "$ref": "#/components/parameters/EventCompanyIdFilter"
          },
          {
            "$ref": "#/components/parameters/EventCreatedAtFilter"
          },
          {
            "$ref": "#/components/parameters/ExpandEvent"
          },
          {
            "$ref": "#/components/parameters/Sort"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/After"
          },
          {
            "$ref": "#/components/parameters/Before"
          }
        ],
        "responses": {
          "200": {
            "description": "One page of events, newest first by default.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "description": "Filter by `type`, `company_id`, or a `created_at` range. Sortable by `created_at`."
      }
    },
    "/sandbox/companies/{companyID}/simulate": {
      "post": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "createSandboxSimulation",
        "summary": "Simulate an event (test keys only)",
        "description": "Moves a test company - or one of its orders, tax filings or documents - the way a live change would, and delivers the resulting event(s) to your test webhooks. Available only with a test key (`clmt_test_`). A live key is refused. Nothing reaches Clemta. The response is the company afterwards.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SandboxSimulateBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The company after the simulated change.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The endpoint is sandbox-only and was called with a live key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/clock": {
      "get": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "getClock",
        "summary": "Read your simulation clock",
        "description": "The clock for the calling key's mode, or 404 when none exists. The clock is a sandbox tool - live keys are refused. Use a test key.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The clock.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Clock"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Live keys cannot use the simulation clock.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "createClock",
        "summary": "Create your simulation clock",
        "description": "Opens the clock for the calling key's mode, frozen at the real current time. One clock exists per mode, so creating again returns the existing clock unchanged. While the clock exists, advancing it runs the renewals that come due on your companies forward, so you can test recurring billing without waiting for real time. Deleting it returns the mode to real time.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The clock - fresh, or the one that already existed.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Clock"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Live keys cannot use the simulation clock.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "deleteClock",
        "summary": "Delete your simulation clock",
        "description": "Removes the mode's clock. The simulated world returns to real time. Nothing already billed is undone - periods the clock advanced over stay billed, and renewal dates advanced into the future are simply not due yet.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "204": {
            "description": "The clock is gone."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Live keys cannot use the simulation clock.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/clock/advance": {
      "post": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "advanceClock",
        "summary": "Advance your simulation clock",
        "description": "Moves the mode's simulated time forward to `to` and runs the time-driven machinery up to it. Every renewal period that comes due before that moment bills, so a monthly order advanced a year bills twelve periods at once. A clock only moves forward, and at most five years in one call. Advancing changes nothing about how new records stamp their own times. It only decides how far \"due\" has looked.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdvanceClockBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The clock at its new simulated time.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Clock"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Live keys cannot use the simulation clock.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/files": {
      "post": {
        "tags": [
          "Files"
        ],
        "operationId": "createFile",
        "summary": "Upload a file",
        "description": "Upload a file to attach elsewhere by id. Send `multipart/form-data` with a `file` part and a `purpose`. `identity_document` uploads are an owner's passport or government ID: attach one to a `document` requirement (`document` on fulfill) or directly at company create (`shareholders[].passport`). `additional_document` uploads answer a form's file field: pass the file id as that field's value on fulfill. Uploads are single-use and write-only - the response carries no download URL and the contents can never be read back through the API. Each purpose sets its own accepted types, size ceiling and file count (PDF, JPEG or PNG and 10MB for documents, smaller for branding images). Content is verified against the declared type.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file",
                  "purpose"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "purpose": {
                    "type": "string",
                    "enum": [
                      "identity_document",
                      "formation_document",
                      "additional_document",
                      "tax_form_1099",
                      "business_logo",
                      "business_icon"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The uploaded file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/File"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Files"
        ],
        "operationId": "listFiles",
        "summary": "List all files",
        "description": "Every file in your account, newest first - Clemta-published deliverables and your own uploads alike. Filter by `purpose`, `source`, `company_id`, `service_order_id` (the documents delivered on one service order) or `kind` (what a published document is).",
        "parameters": [
          {
            "$ref": "#/components/parameters/Sort"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/After"
          },
          {
            "$ref": "#/components/parameters/Before"
          }
        ],
        "responses": {
          "200": {
            "description": "The files, paginated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PagedFileList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{companyID}/files": {
      "get": {
        "tags": [
          "Files"
        ],
        "operationId": "listCompanyFiles",
        "summary": "List a company's documents",
        "description": "Every document Clemta has published on the company, newest first - formation deliverables, filed forms, letters. `file.created` announces each new one.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "responses": {
          "200": {
            "description": "The documents.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileList"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/companies/{companyID}/tax-filings": {
      "post": {
        "tags": [
          "Tax filings"
        ],
        "operationId": "createTaxFiling",
        "summary": "Open a tax filing",
        "description": "Opens a federal or state filing for the current year. One filing per company, type and year. Identity fields prefill from the company. Opening is free - the filing entitlement is spent when the filing is submitted - so a draft can sit as long as it needs to. Pass `submit: true` with a complete form to open and submit in one atomic call.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTaxFilingBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The filing, with its form and readiness.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxFiling"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No filing entitlement remains for an immediate submit - order the matching entitlement product first, then retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A filing for this type and year already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Tax filings"
        ],
        "operationId": "listCompanyTaxFilings",
        "summary": "List a company's tax filings",
        "description": "Every federal and state filing opened on the company, newest year first, with its review status and progress. Each filing is opened by you or your customer against the company's `entitlements`. Read them here.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "responses": {
          "200": {
            "description": "The filings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxFilingList"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{companyID}/tax-filings/{filingID}": {
      "get": {
        "tags": [
          "Tax filings"
        ],
        "operationId": "getTaxFiling",
        "summary": "Retrieve a tax filing",
        "description": "The filing with its questionnaire and readiness. The form reads live, so the latest changes are visible immediately.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/TaxFilingId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The filing.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxFiling"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Tax filings"
        ],
        "operationId": "updateTaxFiling",
        "summary": "Update a tax filing",
        "description": "Replaces the provided form sections on a draft. A section you send replaces the stored one whole, a section you omit stays as it is. Only a draft is editable - after submit, changes go through Clemta.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/TaxFilingId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateTaxFilingBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The filing after the update, with readiness recomputed.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxFiling"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The filing is no longer a draft.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{companyID}/tax-filings/{filingID}/submit": {
      "post": {
        "tags": [
          "Tax filings"
        ],
        "operationId": "submitTaxFiling",
        "summary": "Submit a tax filing",
        "description": "Submits the filing to Clemta for review. This is the one transactional moment - readiness is checked, one filing entitlement is spent, and the filing moves to `in_review`, all together or not at all. A filing already submitted answers its current state, so a retry is a no-op. With no entitlement remaining the draft stays intact - order the matching entitlement product and retry.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/TaxFilingId"
          },
          {
            "$ref": "#/components/parameters/ClemtaVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "The submitted filing.",
            "headers": {
              "Clemta-Version": {
                "$ref": "#/components/headers/ClemtaVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxFiling"
                }
              }
            }
          },
          "400": {
            "description": "The filing is not ready - `missing` on the detail read names each gap.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No filing entitlement remains - order the matching entitlement product first, then retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{companyID}/calendar": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "listCompanyCalendar",
        "summary": "List a company's compliance calendar",
        "description": "The company's upcoming compliance items - annual report and tax deadlines - soonest first. A `calendar.reminder` webhook fires ahead of each one, so you can notify your customer under your own brand. Test-mode companies carry no calendar and answer an empty list.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "responses": {
          "200": {
            "description": "The calendar.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalendarEventList"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Calendar"
        ],
        "operationId": "createCompanyCalendarEvent",
        "summary": "Add a calendar event",
        "description": "Adds your own event to the company's calendar, beside the compliance deadlines. It carries your own title and note, and fires a `calendar.reminder` webhook at each `remind_before_days` point. Works on test-mode companies too - your events are yours, not read through from the compliance calendar.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCalendarEventBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalendarEvent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{companyID}/calendar/{eventID}": {
      "delete": {
        "tags": [
          "Calendar"
        ],
        "operationId": "deleteCompanyCalendarEvent",
        "summary": "Delete a calendar event",
        "description": "Removes one of your own calendar events. Compliance deadlines are read through from the company and cannot be deleted - only events you added.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/CalendarEventId"
          }
        ],
        "responses": {
          "204": {
            "description": "The event was deleted."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/files/{fileID}": {
      "get": {
        "tags": [
          "Files"
        ],
        "operationId": "getFile",
        "summary": "Retrieve a file",
        "parameters": [
          {
            "$ref": "#/components/parameters/FileId"
          }
        ],
        "responses": {
          "200": {
            "description": "The file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/File"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/file-links": {
      "post": {
        "tags": [
          "Files"
        ],
        "operationId": "createFileLink",
        "summary": "Create a file link",
        "description": "Mints a public URL over one of your files: anyone holding the URL can read the contents without authentication, until the link expires. Only shareable files can be linked - Clemta deliverables and branding uploads. A customer identity document is refused.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateFileLinkBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileLink"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Files"
        ],
        "operationId": "listFileLinks",
        "summary": "List all file links",
        "description": "Your file links, newest first. Filter by `file`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Sort"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/After"
          },
          {
            "$ref": "#/components/parameters/Before"
          }
        ],
        "responses": {
          "200": {
            "description": "The links, paginated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PagedFileLinkList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/file-links/{linkID}": {
      "get": {
        "tags": [
          "Files"
        ],
        "operationId": "getFileLink",
        "summary": "Retrieve a file link",
        "parameters": [
          {
            "$ref": "#/components/parameters/FileLinkId"
          }
        ],
        "responses": {
          "200": {
            "description": "The link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileLink"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Files"
        ],
        "operationId": "updateFileLink",
        "summary": "Update a file link",
        "description": "Moves the expiry or replaces the metadata. Set `expires_at` to the literal `now` to expire the link immediately - the way to revoke a URL that is already in someone's hands.",
        "parameters": [
          {
            "$ref": "#/components/parameters/FileLinkId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateFileLinkBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The link afterwards.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileLink"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/file-links/{token}/contents": {
      "get": {
        "tags": [
          "Files"
        ],
        "operationId": "getFileLinkContents",
        "summary": "Read a file link's contents",
        "security": [],
        "description": "The public door a file link's `url` points at: streams the file's bytes with no authentication - the token in the path is the credential. An unknown or expired token answers 404.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "The link token from the file link's url.",
            "schema": {
              "type": "string",
              "pattern": "^flt_[0-9a-f]{48}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file's bytes.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/files/{fileID}/contents": {
      "get": {
        "tags": [
          "Files"
        ],
        "operationId": "getFileContent",
        "summary": "Download a file's bytes",
        "description": "Streams the document itself. The response's Content-Type is the file's own. Content-Disposition carries the filename.",
        "parameters": [
          {
            "$ref": "#/components/parameters/FileId"
          }
        ],
        "responses": {
          "200": {
            "description": "The document bytes.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/requirements": {
      "get": {
        "tags": [
          "Requirements"
        ],
        "operationId": "listRequirements",
        "summary": "List requirements",
        "description": "Everything currently (or previously) needed from you, newest first. Filter by company and/or status. Poll `status=open` to see what is outstanding.",
        "parameters": [
          {
            "name": "company",
            "in": "query",
            "required": false,
            "description": "Only this company's requirements.",
            "schema": {
              "type": "string",
              "pattern": "^cmp_[0-9A-Za-z]{22}$"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "resolved",
                "canceled"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The requirements, newest first (at most 100).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequirementList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/requirements/{requirementID}": {
      "get": {
        "tags": [
          "Requirements"
        ],
        "operationId": "getRequirement",
        "summary": "Retrieve a requirement",
        "description": "One requirement. An open `form` requirement carries the live `form` schema - the fields to collect next.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequirementId"
          }
        ],
        "responses": {
          "200": {
            "description": "The requirement.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Requirement"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/requirements/{requirementID}/fulfill": {
      "post": {
        "tags": [
          "Requirements"
        ],
        "operationId": "fulfillRequirement",
        "summary": "Fulfill a requirement",
        "description": "Resolve an open requirement with its answers - a `form`, `name_change` or `information` requirement with `values`, a `document` requirement with an uploaded file by id (`document`, or `documents` for several pages). Emits `requirement.fulfilled`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequirementId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FulfillRequirementBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The resolved requirement.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Requirement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/companies/{companyID}/verification-sessions": {
      "post": {
        "tags": [
          "Requirements"
        ],
        "operationId": "createVerificationSession",
        "summary": "Create a hosted verification session",
        "description": "Mints a fresh URL for the hosted identity-document page, for one owner of this company. Live mode only - the hosted page collects a real identity document. Test companies rehearse verification through the sandbox simulate endpoint instead. Requires the verification page to be configured first (your display name and privacy policy - the page presents them to your customer). Refused when the owner's document is already received.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateVerificationSessionBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationSession"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/companies/{companyID}/signing-sessions": {
      "post": {
        "tags": [
          "Requirements"
        ],
        "operationId": "createSigningSession",
        "summary": "Create a hosted signing session",
        "description": "Mints a fresh hosted signing URL for one open signature requirement. Your hosted page must be configured - it presents your brand and legal links while collecting the signature. In test mode the signature has no provider, so the page presents a test completion rather than a signing frame.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSigningSessionBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SigningSession"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/companies/{companyID}/signature-signers": {
      "post": {
        "tags": [
          "Requirements"
        ],
        "operationId": "supplySignerEmail",
        "summary": "Supply a signer's email",
        "description": "Provides the email for a deferred signer - one Clemta opened with a name but no email (status `pending_email`). Once every signer on the document has an email, the signing round opens for all of them and you can mint their sessions. Live mode only. The email is not required to be one of the company's owners. A deferred signer is an outside party by design.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SupplySignerEmailBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The signature requirement with the signer's email set.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Requirement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/companies/{companyID}/fixed-assets": {
      "get": {
        "tags": [
          "Fixed assets"
        ],
        "operationId": "listFixedAssets",
        "summary": "List a company's fixed assets",
        "description": "The company's fixed-asset register. The federal tax filing draws from these.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "responses": {
          "200": {
            "description": "The register.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FixedAssetList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Fixed assets"
        ],
        "operationId": "createFixedAsset",
        "summary": "Add a fixed asset",
        "description": "Adds a fixed asset to the company's register. It is assigned the next `AST-` number. A later federal tax filing snapshots the register, so an asset added here reaches the filing.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateFixedAssetBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created asset.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FixedAsset"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/companies/{companyID}/fixed-assets/{fixedAssetID}": {
      "get": {
        "tags": [
          "Fixed assets"
        ],
        "operationId": "getFixedAsset",
        "summary": "Retrieve a fixed asset",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/FixedAssetId"
          }
        ],
        "responses": {
          "200": {
            "description": "The asset.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FixedAsset"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Fixed assets"
        ],
        "operationId": "updateFixedAsset",
        "summary": "Update a fixed asset",
        "description": "Sparse update - a field left out is unchanged.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/FixedAssetId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateFixedAssetBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated asset.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FixedAsset"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Fixed assets"
        ],
        "operationId": "deleteFixedAsset",
        "summary": "Delete a fixed asset",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/FixedAssetId"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/companies/{companyID}/officers": {
      "get": {
        "tags": [
          "Officers"
        ],
        "operationId": "listOfficers",
        "summary": "List a company's officers and directors",
        "description": "The company's management roster. A director is an officer holding role `director`. There is no separate directors list.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "responses": {
          "200": {
            "description": "The roster.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OfficerList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Officers"
        ],
        "operationId": "createOfficer",
        "summary": "Add an officer or director",
        "description": "Seats an officer on the company's roster with the roles given. An officer whose `email` matches a shareholder's is seated as that owner. For a company already handed off to Clemta, the change reaches Clemta. The roles are validated against the entity type (LLC vs C-Corp catalogues).",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOfficerBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The seated officer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyOfficer"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/companies/{companyID}/officers/{officerID}": {
      "post": {
        "tags": [
          "Officers"
        ],
        "operationId": "updateOfficer",
        "summary": "Update an officer or director",
        "description": "Replaces the officer's roles and identity. Send the full desired state. The roles are validated against the entity type.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/OfficerId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOfficerBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated officer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyOfficer"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Officers"
        ],
        "operationId": "deleteOfficer",
        "summary": "Remove an officer or director",
        "description": "Removes the officer from the roster.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyId"
          },
          {
            "$ref": "#/components/parameters/OfficerId"
          }
        ],
        "responses": {
          "204": {
            "description": "Removed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/signing-links/{token}": {
      "get": {
        "tags": [
          "Requirements"
        ],
        "operationId": "getSigningLinkContext",
        "summary": "Read a signing link",
        "security": [],
        "description": "What the hosted signing page renders - the ask, the partner's branding and the embedded signing session. Authenticated by the token itself, no API key. The signature itself completes inside the embedded session. The requirement resolves once the signature completes, and the page only ever reads.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequirementToken"
          }
        ],
        "responses": {
          "200": {
            "description": "The context.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SigningContext"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/signing-links/{token}/complete": {
      "post": {
        "tags": [
          "Requirements"
        ],
        "operationId": "completeSigningLink",
        "summary": "Complete a test signing link",
        "security": [],
        "description": "Completes a signature in TEST MODE, standing in for the signer finishing the document. Authenticated by the token itself, no API key. It marks every signer signed and resolves the requirement, so your `requirement.signature.signed` and `requirement.fulfilled` webhooks fire exactly as a live completion would - letting you rehearse the whole signature flow in sandbox. Available only for a test-mode signature (`livemode: false`) - a live signature is refused, since it resolves solely through the signing provider. Idempotent - completing an already-completed link is a no-op that returns its current state.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequirementToken"
          }
        ],
        "responses": {
          "200": {
            "description": "The signing context after completion.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SigningContext"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/signing-links/{token}/view": {
      "post": {
        "tags": [
          "Requirements"
        ],
        "operationId": "viewSigningLink",
        "summary": "View a test signing link",
        "security": [],
        "description": "Marks the signer as having opened the document, in TEST MODE, so your `requirement.signature.viewed` webhook fires - the sandbox stand-in for the provider's form.viewed (a separate event fired when the signer opens the signing screen). Authenticated by the token itself, no API key. Available only for a test-mode signature - idempotent.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequirementToken"
          }
        ],
        "responses": {
          "200": {
            "description": "The signing context.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SigningContext"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/requirement-links/{token}": {
      "get": {
        "tags": [
          "Requirements"
        ],
        "operationId": "getRequirementLinkContext",
        "summary": "Read a hosted link's context",
        "security": [],
        "description": "What the hosted page renders: what is asked and of whom, plus your hosted-page branding. Authenticated by the token itself - no API key.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequirementToken"
          }
        ],
        "responses": {
          "200": {
            "description": "The context.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequirementContext"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/requirement-links/{token}/document": {
      "put": {
        "tags": [
          "Requirements"
        ],
        "operationId": "putRequirementLinkDocument",
        "summary": "Upload the document set through a hosted link",
        "security": [],
        "description": "The hosted page's upload: the link URL itself is the credential - a time-limited, single-purpose capability, no API key. Send the COMPLETE document set in one request: `multipart/form-data` with one part per page (a two-sided ID is two parts), or the raw bytes of a single file with its Content-Type. The request itself is completeness - there is no add-another-page call.\nValidation: PDF, JPEG and PNG only, at most 10 MB per file, at most 2 files, and the bytes must actually be the format the Content-Type declares (file signatures are checked) - a mislabeled file is refused with `invalid_request`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequirementToken"
          },
          {
            "name": "filename",
            "in": "query",
            "required": false,
            "description": "The filename, when the body is raw bytes rather than multipart.",
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "files": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  }
                }
              }
            },
            "application/pdf": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The context afterwards - resolved when the set completes the ask.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequirementContext"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "webhooks": {
    "company.created": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyCreated",
        "summary": "A company was created",
        "description": "Sent to your configured endpoint when a company is created through the API, in either mode (a `clmt_test_` key's events carry `livemode: false`). The request body is the `event` resource. Fetch the company it names for its current state. Verify the `Clemta-Webhook-Signature` header with your endpoint's signing secret before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.status.changed": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyStatusChanged",
        "summary": "A company's formation status changed",
        "description": "Sent when a company moves between formation states. The request body is the `event` resource. Branch on the company's status after fetching it rather than on the event type alone. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.verified": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyVerified",
        "summary": "A company's owners cleared verification",
        "description": "Sent once, when the last owner's identity document lands and the company is ready for formation - well before incorporation (which has its own event, `company.incorporated`). Verification never regresses. The request body is the `event` resource. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.incorporated": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyIncorporated",
        "summary": "A company was incorporated",
        "description": "Sent once, when the state accepts the filing and the company becomes active - the milestone to tell your customer about. `company.status.changed` fires as well. This event exists so the moment is a single, unmistakable signal. The request body is the `event` resource. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.onboarding.completed": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyOnboardingCompleted",
        "summary": "A pre-existing company is fully onboarded",
        "description": "Sent once, when Clemta finishes taking a pre_existing company onto the platform - the moment a newly formed company would instead announce `company.incorporated`. A company incorporated years before it arrived never fires the incorporation event. This is its counterpart milestone. `data.object` is the company. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.name.changed": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyNameChanged",
        "summary": "A company's legal name changed",
        "description": "Sent when Clemta changes the company's legal name - typically to clear a conflict with the state. The payload carries the new name. Update your own records and tell your customer. The request body is the `event` resource. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.ein.assigned": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyEinAssigned",
        "summary": "A company received its EIN",
        "description": "Sent once, when the IRS issues the company's federal tax id and Clemta records it. The payload carries `ein`. The request body is the `event` resource. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.document.received": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyDocumentReceived",
        "summary": "An owner's identity document was received",
        "description": "Sent when an individual owner uploads their identity document. The request body is the `event` resource. Fetch the company it names to see which owners are still outstanding. When the last document lands, the company also emits `company.status.changed`. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.dissolved": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyDissolved",
        "summary": "The company was dissolved",
        "description": "Sent exactly once, when a dissolution order completes and the company reaches its terminal `dissolved` status. Every recurring service on the company stops renewing at that moment, open requirements are closed, and nothing further can be ordered to it. The request body is the `event` resource, whose `data.object` is the company as of the dissolution. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.updated": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyUpdated",
        "summary": "A company's details changed",
        "description": "Sent when Clemta edits the company's identity - entity type, state, industry, share structure, formation date, legal address or the owner roster. `data.object` is the company as it now stands. Verify the `Clemta-Webhook-Signature` header before trusting the payload.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "company.entitlements.changed": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCompanyEntitlementsChanged",
        "summary": "A company's remaining rights changed",
        "description": "Sent when the company's `entitlements` move - a tax-filing credit added by an order or by Clemta, or consumed by a filing. `data.object` is the company with its current `entitlements`. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "tax_filing.created": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onTaxFilingCreated",
        "summary": "A tax filing was opened",
        "description": "Sent when a federal or state tax filing is opened on the company. `data.object` is the tax filing. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "tax_filing.status.changed": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onTaxFilingStatusChanged",
        "summary": "A tax filing moved",
        "description": "Sent when Clemta moves a tax filing's `status` or `progress`. `data.object` is the tax filing as of the change. Branch on its fields. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "service_order.status.changed": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onServiceOrderStatusChanged",
        "summary": "A service order's status changed",
        "description": "Sent when a service order is created or its fulfilment status changes, including cancellation. The request body is the `event` resource, whose `data.object` is the service order as of the change. Branch on its status rather than on the event type alone. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "service_order.completed": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onServiceOrderCompleted",
        "summary": "A service order was fulfilled",
        "description": "Sent when the order reaches `completed`. `completed_at` is set then, and a repeated echo of the same position does not fire it again. If Clemta moves the order back off its last step it reopens and `completed_at` clears, so the event fires again when the order completes once more. The request body is the `event` resource, whose `data.object` is the completed service order. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "service_order.updated": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onServiceOrderUpdated",
        "summary": "A service order was changed outside your own call",
        "description": "Sent when an order's options or price change without you calling - today, Clemta reversing an options upgrade it could not deliver: the difference you were billed is credited back and the order returns to its previous choices and price. The request body is the `event` resource, whose `data.object` is the order as of the change. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "service_order.quoted": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onServiceOrderQuoted",
        "summary": "Clemta priced a quote order",
        "description": "Sent when Clemta set the price on a quote_pending order - a product priced per piece of work, such as catch-up bookkeeping. The request body is the `event` resource, whose `data.object` is the service order carrying its `quote` object: the amount, and `expires_at`, the acceptance window. Accept with `accept_quote: true` on the order update endpoint before the window lapses. Nothing is billed until you do, and cancelling the order declines the quote. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "service_order.renewal_canceled": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onServiceOrderRenewalCanceled",
        "summary": "A renewal cancellation was approved",
        "description": "Sent when Clemta approves your cancellation request on a recurring order. The service runs to `renewal_ends_at` and is not billed past it - except a product billed in arrears, whose running period still bills at that moment, since it was served. The request body is the `event` resource, whose `data.object` is the service order as of the approval. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "service_order.renewal_cancel_denied": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onServiceOrderRenewalCancelDenied",
        "summary": "A renewal cancellation was denied",
        "description": "Sent when Clemta denies your cancellation request on a recurring order. The request is cleared and the order keeps renewing as before - contact support for the reasoning. The request body is the `event` resource, whose `data.object` is the service order as of the decision. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "requirement.created": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onRequirementCreated",
        "summary": "Something is needed from you or your customer",
        "description": "Sent when a requirement opens: an owner's identity document, a service-order form, or something Clemta asked for (a company-name change, extra information). The request body is the `event` resource whose `data.object` is the requirement. Fulfill it over the API or hand your customer a hosted link. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "requirement.fulfilled": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onRequirementFulfilled",
        "summary": "A requirement was fulfilled",
        "description": "Sent when an open requirement resolves - by your API call or by your customer through a hosted link. The request body is the `event` resource whose `data.object` is the requirement with its response. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "requirement.canceled": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onRequirementCanceled",
        "summary": "A requirement was canceled",
        "description": "Sent when an open requirement closes WITHOUT being fulfilled - a signer declining a signature request, or Clemta withdrawing the ask. The request body is the `event` resource whose `data.object` is the requirement. Its `cancel_reason` says why, in words safe to show your customer. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "requirement.signature.viewed": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onRequirementSignatureViewed",
        "summary": "A signer opened a signature document",
        "description": "Sent the first time a signer opens the signature document. A requirement with several signers fires this once per signer. The request body is the `event` resource whose `data.object` is the requirement with its `signers`. Progress only - the document is not signed yet. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "requirement.signature.signed": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onRequirementSignatureSigned",
        "summary": "A signer signed a signature document",
        "description": "Sent when one signer completes their part of a signature document. A document with several signers fires this once per signer. The requirement itself resolves (requirement.fulfilled) only when the last of them signs. The request body is the `event` resource whose `data.object` is the requirement with its `signers`. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "file.created": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onFileCreated",
        "summary": "A document is ready for you",
        "description": "Sent when Clemta publishes a document on one of your companies. The request body is the `event` resource whose `data.object` is the file. Download the bytes from the file's content endpoint. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "calendar.reminder": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onCalendarReminder",
        "summary": "A compliance deadline is approaching",
        "description": "Sent ahead of a company's compliance calendar deadline, once per reminder point. No mail is sent to your customer - relay the reminder under your own brand. `data.object` is the calendar event with `due_at` and the `remind_at` that fired. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    },
    "invoice.finalized": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "onInvoiceFinalized",
        "summary": "A monthly invoice was finalized",
        "description": "Sent when your month-end invoice is raised. The request body is the `event` resource, whose `data.object` is the invoice. It is collected automatically from your payment method on file. Verify the `Clemta-Webhook-Signature` header before trusting the payload, and respond with any 2xx to acknowledge - a non-2xx or a timeout is retried with backoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged. Any 2xx marks the delivery received and stops retries."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your API key, e.g. `Authorization: Bearer clmt_test_`. Live keys use the `clmt_live_` prefix.\n"
      }
    },
    "parameters": {
      "ClemtaVersion": {
        "name": "Clemta-Version",
        "in": "header",
        "required": false,
        "description": "Date-based API version to run this request against.",
        "schema": {
          "type": "string",
          "example": "2026-08-13"
        }
      },
      "Sort": {
        "name": "sort",
        "in": "query",
        "required": false,
        "description": "Comma-separated fields to sort by, a minus prefix for descending (for example `-created_at`). Each endpoint's sortable fields are in its description. An unsupported one is rejected with a suggestion.",
        "schema": {
          "type": "string",
          "example": "-created_at,name"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 25
        }
      },
      "After": {
        "name": "after",
        "in": "query",
        "required": false,
        "description": "Use the page's `end_cursor` as the `after` value to fetch the next page. Cursors are opaque and only valid for the listing that minted them.",
        "schema": {
          "type": "string"
        }
      },
      "Before": {
        "name": "before",
        "in": "query",
        "required": false,
        "description": "Use the page's `start_cursor` as the `before` value to fetch the previous page. Cannot be combined with `after`.",
        "schema": {
          "type": "string"
        }
      },
      "AccountId": {
        "name": "accountID",
        "in": "path",
        "required": true,
        "description": "The account id.",
        "schema": {
          "type": "string",
          "pattern": "^acct_[0-9A-Za-z]{22}$"
        }
      },
      "Status": {
        "name": "status",
        "in": "query",
        "required": false,
        "style": "deepObject",
        "explode": true,
        "allowReserved": true,
        "description": "Filter by status. A bare value is an exact match (`status=active`), operators go in brackets: `status[neq]=cancelled`, `status[in]=in_progress,active`.",
        "schema": {
          "anyOf": [
            {
              "type": "string",
              "title": "Exact match",
              "enum": [
                "requires_information",
                "in_progress",
                "active",
                "cancelled"
              ]
            },
            {
              "type": "object",
              "title": "Operators",
              "additionalProperties": false,
              "properties": {
                "eq": {
                  "type": "string",
                  "enum": [
                    "requires_information",
                    "in_progress",
                    "active",
                    "cancelled"
                  ],
                  "description": "Exact match (same as the bare form)."
                },
                "neq": {
                  "type": "string",
                  "enum": [
                    "requires_information",
                    "in_progress",
                    "active",
                    "cancelled"
                  ],
                  "description": "Any status except this one."
                },
                "in": {
                  "type": "string",
                  "description": "Comma-separated list, matches any of them."
                },
                "nin": {
                  "type": "string",
                  "description": "Comma-separated list, matches none of them."
                }
              }
            }
          ]
        }
      },
      "AccountIdFilter": {
        "name": "account_id",
        "in": "query",
        "required": false,
        "style": "deepObject",
        "explode": true,
        "allowReserved": true,
        "description": "Filter by the account (the incorporator) that owns the company. A bare value is an exact match (`account_id=acct_...`). Operators go in brackets (`account_id[in]=acct_a,acct_b`). The `Clemta-Account` header resolves to this same filter and overrides any value sent here.",
        "schema": {
          "anyOf": [
            {
              "type": "string",
              "title": "Exact match",
              "pattern": "^acct_[0-9A-Za-z]{22}$"
            },
            {
              "type": "object",
              "title": "Operators",
              "additionalProperties": false,
              "properties": {
                "eq": {
                  "type": "string",
                  "description": "Exact match (same as the bare form)."
                },
                "in": {
                  "type": "string",
                  "description": "Comma-separated list, matches any of them."
                },
                "nin": {
                  "type": "string",
                  "description": "Comma-separated list, matches none of them."
                }
              }
            }
          ]
        }
      },
      "ExpandCompany": {
        "name": "expand[]",
        "in": "query",
        "required": false,
        "description": "Relations to embed. Expandable: account, requirements (the open requirements behind `open_requirements`), service_orders (every order on the company, auto-attached mandatory products included).",
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "account",
              "requirements",
              "service_orders"
            ]
          }
        }
      },
      "ClemtaAccount": {
        "name": "Clemta-Account",
        "in": "header",
        "required": false,
        "description": "The account (the incorporator) to create the company under, when it already exists. Omit it and pass `account` in the body to create one at the same time. Set one or the other, never both.",
        "schema": {
          "type": "string",
          "pattern": "^acct_[0-9A-Za-z]{22}$",
          "example": "acct_0346sFPEvSkJvY8vt14NNw"
        }
      },
      "CompanyId": {
        "name": "companyID",
        "in": "path",
        "required": true,
        "description": "ID of the company.",
        "schema": {
          "type": "string",
          "pattern": "^cmp_[0-9A-Za-z]{22}$"
        },
        "example": "cmp_0346sFPEvSkJvY8vt14NNw"
      },
      "ExpandServiceOrder": {
        "name": "expand[]",
        "in": "query",
        "required": false,
        "description": "Relations to embed. Expandable: files (the documents delivered on the order, newest first - the same set GET /v1/files?service_order_id= answers).",
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "files"
            ]
          }
        }
      },
      "ServiceOrderId": {
        "name": "orderID",
        "in": "path",
        "required": true,
        "description": "ID of the service order.",
        "schema": {
          "type": "string",
          "pattern": "^so_[0-9A-Za-z]{22}$"
        },
        "example": "so_0346sFPEvSkJvY8vt14NNw"
      },
      "StatusTokenId": {
        "name": "tokenID",
        "in": "path",
        "required": true,
        "description": "The status token's management id.",
        "schema": {
          "type": "string",
          "pattern": "^stok_[0-9A-Za-z]{22}$"
        },
        "example": "stok_0346sFPEvSkJvY8vt14NNw"
      },
      "EventTypeFilter": {
        "name": "type",
        "in": "query",
        "required": false,
        "style": "deepObject",
        "explode": true,
        "allowReserved": true,
        "description": "Filter by event type. A bare value is an exact match (`type=company.status.changed`). Operators go in brackets (`type[in]=company.created,company.incorporated`).",
        "schema": {
          "anyOf": [
            {
              "type": "string",
              "title": "Exact match"
            },
            {
              "type": "object",
              "title": "Operators",
              "additionalProperties": false,
              "properties": {
                "eq": {
                  "type": "string",
                  "description": "Exact match (same as the bare form)."
                },
                "in": {
                  "type": "string",
                  "description": "Comma-separated list, matches any of them."
                },
                "nin": {
                  "type": "string",
                  "description": "Comma-separated list, matches none of them."
                }
              }
            }
          ]
        }
      },
      "EventCompanyIdFilter": {
        "name": "company_id",
        "in": "query",
        "required": false,
        "style": "deepObject",
        "explode": true,
        "allowReserved": true,
        "description": "Filter to the events of one company. A bare value is an exact match (`company_id=cmp_...`). Operators go in brackets (`company_id[in]=cmp_a,cmp_b`).",
        "schema": {
          "anyOf": [
            {
              "type": "string",
              "title": "Exact match",
              "pattern": "^cmp_[0-9A-Za-z]{22}$"
            },
            {
              "type": "object",
              "title": "Operators",
              "additionalProperties": false,
              "properties": {
                "eq": {
                  "type": "string",
                  "description": "Exact match (same as the bare form)."
                },
                "in": {
                  "type": "string",
                  "description": "Comma-separated list, matches any of them."
                },
                "nin": {
                  "type": "string",
                  "description": "Comma-separated list, matches none of them."
                }
              }
            }
          ]
        }
      },
      "EventCreatedAtFilter": {
        "name": "created_at",
        "in": "query",
        "required": false,
        "style": "deepObject",
        "explode": true,
        "allowReserved": true,
        "description": "Filter by creation time (RFC 3339). A bare value is an exact match. Range operators go in brackets: `created_at[gte]=2026-09-01T00:00:00Z`, `created_at[lt]=...`. Combine a `gte` lower bound with cursor paging to sweep the stream from a known point - see the webhooks guide on reconciling by polling.",
        "schema": {
          "anyOf": [
            {
              "type": "string",
              "title": "Exact match",
              "format": "date-time"
            },
            {
              "type": "object",
              "title": "Operators",
              "additionalProperties": false,
              "properties": {
                "gt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Strictly after this moment."
                },
                "gte": {
                  "type": "string",
                  "format": "date-time",
                  "description": "At or after this moment."
                },
                "lt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Strictly before this moment."
                },
                "lte": {
                  "type": "string",
                  "format": "date-time",
                  "description": "At or before this moment."
                }
              }
            }
          ]
        }
      },
      "ExpandEvent": {
        "name": "expand[]",
        "in": "query",
        "required": false,
        "description": "Relations to embed. Expandable: company (the full company the event is about, when it carries a company_id). Requires a key scoped to read companies.",
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "company"
            ]
          }
        }
      },
      "TaxFilingId": {
        "name": "filingID",
        "in": "path",
        "required": true,
        "description": "ID of the tax filing.",
        "schema": {
          "type": "string",
          "pattern": "^txf_[0-9A-Za-z]{22}$"
        },
        "example": "txf_0346sFPEvSkJvY8vt14NNw"
      },
      "CalendarEventId": {
        "name": "eventID",
        "in": "path",
        "required": true,
        "description": "ID of the calendar event.",
        "schema": {
          "type": "string",
          "pattern": "^cal_[0-9A-Za-z]{22}$"
        },
        "example": "cal_0346sFPEvSkJvY8vt14NNw"
      },
      "FileId": {
        "name": "fileID",
        "in": "path",
        "required": true,
        "description": "ID of the file.",
        "schema": {
          "type": "string",
          "pattern": "^file_[0-9A-Za-z]{22}$"
        },
        "example": "file_0346sFPEvSkJvY8vt14NNw"
      },
      "FileLinkId": {
        "name": "linkID",
        "in": "path",
        "required": true,
        "description": "The file link's id.",
        "schema": {
          "type": "string",
          "pattern": "^link_[0-9A-Za-z]{22}$"
        }
      },
      "RequirementId": {
        "name": "requirementID",
        "in": "path",
        "required": true,
        "description": "ID of the requirement.",
        "schema": {
          "type": "string",
          "pattern": "^rqmt_[0-9A-Za-z]{22}$"
        },
        "example": "rqmt_0346sFPEvSkJvY8vt14NNw"
      },
      "FixedAssetId": {
        "name": "fixedAssetID",
        "in": "path",
        "required": true,
        "description": "ID of the fixed asset.",
        "schema": {
          "type": "string",
          "pattern": "^fxa_[0-9A-Za-z]{22}$"
        },
        "example": "fxa_0346sFPEvSkJvY8vt14NNw"
      },
      "OfficerId": {
        "name": "officerID",
        "in": "path",
        "required": true,
        "description": "ID of the officer.",
        "schema": {
          "type": "string",
          "pattern": "^off_[0-9A-Za-z]{22}$"
        },
        "example": "off_0346sFPEvSkJvY8vt14NNw"
      },
      "RequirementToken": {
        "name": "token",
        "in": "path",
        "required": true,
        "description": "The hosted token from a document link.",
        "schema": {
          "type": "string",
          "pattern": "^rql_[0-9a-f]{48}$"
        }
      }
    },
    "headers": {
      "ClemtaVersion": {
        "description": "The API version the request was executed against.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "Me": {
        "type": "object",
        "required": [
          "object",
          "partner_id",
          "livemode",
          "key_last4",
          "api_version"
        ],
        "additionalProperties": false,
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "me"
            ],
            "description": "Entity name. Identifies this object when it arrives without its URL - nested under an `expand[]`, inside an event payload, or in a webhook."
          },
          "partner_id": {
            "type": "string",
            "description": "Identifier of the partner this key belongs to."
          },
          "livemode": {
            "type": "boolean",
            "description": "False for `clmt_test_` keys."
          },
          "key_last4": {
            "type": "string",
            "description": "Last four characters of the presented key."
          },
          "api_version": {
            "type": "string",
            "description": "Effective API version for this request."
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Error response: a stable machine-readable `code`, human-readable `title`/`detail`, and for validation failures an `errors` array naming every violating field.",
        "required": [
          "type",
          "title",
          "status",
          "code"
        ],
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "description": "Link to the error reference entry for this code.",
            "example": "https://docs.clemta.com/partner/errors#resource_already_exists"
          },
          "title": {
            "type": "string",
            "description": "Short human summary of the error class."
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "minimum": 100,
            "maximum": 599,
            "description": "HTTP status code, also included in the body."
          },
          "code": {
            "type": "string",
            "enum": [
              "api_key_invalid",
              "api_key_expired",
              "insufficient_scope",
              "ip_address_not_allowed",
              "invalid_request",
              "invalid_api_version",
              "resource_missing",
              "method_not_allowed",
              "test_mode_only",
              "resource_already_exists",
              "idempotency_key_mismatch",
              "idempotency_key_in_use",
              "request_too_large",
              "billing_account_inactive",
              "entitlement_required",
              "rate_limit",
              "api_error"
            ],
            "description": "Stable machine-readable code - branch on this, never on `detail`."
          },
          "detail": {
            "type": "string",
            "description": "Human-readable specifics of this occurrence, wording may change."
          },
          "request_id": {
            "type": "string",
            "description": "Identifier of this request. Quote it in a support request so we can trace the failure."
          },
          "errors": {
            "type": "array",
            "description": "Present on validation failures: one entry per violating field.",
            "items": {
              "type": "object",
              "required": [
                "reason"
              ],
              "additionalProperties": false,
              "properties": {
                "reason": {
                  "type": "string"
                },
                "location": {
                  "type": "string",
                  "description": "JSONPath of the failing field, e.g. `$.name`."
                },
                "validation_type": {
                  "type": "string",
                  "description": "Schema keyword that failed."
                },
                "how_to_fix": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Page": {
        "type": "object",
        "description": "Cursor-pagination block carried by every list response.",
        "required": [
          "start_cursor",
          "end_cursor",
          "has_next_page",
          "has_prev_page",
          "limit",
          "total"
        ],
        "properties": {
          "start_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Use as the `before` query parameter to load the previous page. `null` when the page is empty. Opaque, internal structure may change."
          },
          "end_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Use as the `after` query parameter to load the next page. `null` when the page is empty. Opaque, internal structure may change."
          },
          "has_next_page": {
            "type": "boolean",
            "description": "Whether a next page exists."
          },
          "has_prev_page": {
            "type": "boolean",
            "description": "Whether a previous page exists."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "The page size this response was built with."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Count of items across all pages of the filtered listing."
          }
        }
      },
      "Account": {
        "type": "object",
        "required": [
          "object",
          "id",
          "livemode",
          "first_name",
          "last_name",
          "email",
          "created_at"
        ],
        "additionalProperties": false,
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "account"
            ],
            "description": "Entity name. Identifies this object when it arrives without its URL."
          },
          "id": {
            "type": "string",
            "pattern": "^acct_[0-9A-Za-z]{22}$",
            "description": "Identifier of the account.",
            "example": "acct_0346sFPEvSkJvY8vt14NNw"
          },
          "external_id": {
            "type": "string",
            "description": "Your own identifier for this account, unique across your accounts."
          },
          "livemode": {
            "type": "boolean",
            "description": "Whether this account was created with a live key."
          },
          "first_name": {
            "type": "string",
            "description": "The customer's first name."
          },
          "last_name": {
            "type": "string",
            "description": "The customer's last name."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The customer's email. Stored as contact data only - the customer never receives any message from Clemta."
          },
          "phone": {
            "type": "string",
            "description": "The customer's phone number."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Your own key-value pairs, stored and returned verbatim. Clemta never reads them. Use them to correlate the account with your system."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AccountList": {
        "type": "object",
        "required": [
          "object",
          "page",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ],
            "description": "Entity name."
          },
          "page": {
            "$ref": "#/components/schemas/Page"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Account"
            }
          }
        }
      },
      "CreateAccountBody": {
        "type": "object",
        "required": [
          "first_name",
          "last_name",
          "email"
        ],
        "additionalProperties": false,
        "properties": {
          "external_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Your own identifier for this account. Must be unique across your accounts. Reusing one is rejected. Use `Idempotency-Key` to retry safely."
          },
          "first_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "pattern": "^[^\\r\\n\\t]+$",
            "description": "The customer's first name."
          },
          "last_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "pattern": "^[^\\r\\n\\t]+$",
            "description": "The customer's last name."
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "description": "The customer's email, stored as contact data only."
          },
          "phone": {
            "type": "string",
            "minLength": 7,
            "maxLength": 20,
            "pattern": "^[0-9+()\\s.-]+$",
            "description": "The customer's phone number. Digits with an optional `+`, spaces, and `()`.-` separators."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Your own key-value pairs, stored and returned verbatim."
          }
        }
      },
      "UpdateAccountBody": {
        "type": "object",
        "required": [
          "metadata"
        ],
        "additionalProperties": false,
        "properties": {
          "metadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": true,
            "description": "Replaces the account's metadata with this set. Send the full map you want stored. An empty object clears it. Your own key-value pairs, returned verbatim."
          }
        }
      },
      "StateCode": {
        "type": "string",
        "description": "US state of formation, as a two-letter code.",
        "example": "DE",
        "enum": [
          "AL",
          "AK",
          "AZ",
          "AR",
          "CA",
          "CO",
          "CT",
          "DE",
          "FL",
          "GA",
          "HI",
          "ID",
          "IL",
          "IN",
          "IA",
          "KS",
          "KY",
          "LA",
          "ME",
          "MD",
          "MA",
          "MI",
          "MN",
          "MS",
          "MO",
          "MT",
          "NE",
          "NV",
          "NH",
          "NJ",
          "NM",
          "NY",
          "NC",
          "ND",
          "OH",
          "OK",
          "OR",
          "PA",
          "RI",
          "SC",
          "SD",
          "TN",
          "TX",
          "UT",
          "VT",
          "VA",
          "WA",
          "WV",
          "WI",
          "WY",
          "DC"
        ]
      },
      "Address": {
        "type": "object",
        "required": [
          "country",
          "line1",
          "city",
          "state",
          "postal_code"
        ],
        "additionalProperties": false,
        "description": "A postal address.",
        "properties": {
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "ISO 3166-1 alpha-2 country code."
          },
          "line1": {
            "type": "string",
            "maxLength": 255
          },
          "line2": {
            "type": "string",
            "maxLength": 255
          },
          "city": {
            "type": "string",
            "maxLength": 120
          },
          "state": {
            "type": "string",
            "maxLength": 120
          },
          "postal_code": {
            "type": "string",
            "maxLength": 20
          }
        }
      },
      "ForeignQualification": {
        "type": "object",
        "required": [
          "state",
          "line1",
          "city",
          "postal_code"
        ],
        "additionalProperties": false,
        "description": "A US state the company is registered to do business in beside its formation state, with the registered address there.",
        "properties": {
          "state": {
            "$ref": "#/components/schemas/StateCode"
          },
          "line1": {
            "type": "string",
            "maxLength": 255
          },
          "line2": {
            "type": "string",
            "maxLength": 255
          },
          "city": {
            "type": "string",
            "maxLength": 120
          },
          "postal_code": {
            "type": "string",
            "maxLength": 20
          }
        }
      },
      "CompanyEntitlements": {
        "type": "object",
        "description": "Rights the company holds, as counts remaining. An order for an entitlement product adds one. A tax filing consumes one when it is submitted. Some may be granted directly. `company.entitlements.changed` announces every move.",
        "properties": {
          "federal_tax_filing": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "Federal tax filings the company may still open.",
            "example": 1
          },
          "state_tax_filing": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "State tax / annual compliance filings the company may still open.",
            "example": 0
          }
        }
      },
      "FieldConditional": {
        "type": "object",
        "description": "This field applies only while another field holds one of the listed values.",
        "required": [
          "field",
          "values"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Key of the controlling field."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any of these values on the controlling field switches this one on."
          }
        }
      },
      "FieldValidation": {
        "type": "object",
        "description": "Constraints an answer must satisfy beyond its type. The server enforces these. A violation answers `invalid_request` with the field named in `errors[]`.",
        "properties": {
          "pattern": {
            "type": "string",
            "description": "Regular expression a text answer must match."
          },
          "min_length": {
            "type": "integer"
          },
          "max_length": {
            "type": "integer"
          },
          "min": {
            "type": "number",
            "description": "Lower bound for a number."
          },
          "max": {
            "type": "number"
          }
        }
      },
      "FieldFileRule": {
        "type": "object",
        "description": "Constraints on a file field's upload.",
        "properties": {
          "accepted_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Media types or extensions accepted (e.g. `application/pdf`, `jpg`). Absent means PDF, JPEG and PNG."
          },
          "max_size_bytes": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "ServiceFormFieldDef": {
        "type": "object",
        "description": "One field of a form. It carries every attribute you need to render the field in your own UI, and the server validates answers against the same definition.",
        "required": [
          "field_name",
          "field_type"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Stable field key - pass it back as the answer's `key`."
          },
          "field_name": {
            "type": "string",
            "description": "The field's label."
          },
          "field_type": {
            "type": "string",
            "enum": [
              "text",
              "textarea",
              "number",
              "date",
              "boolean",
              "select",
              "multi_select",
              "file",
              "email",
              "phone",
              "address"
            ],
            "description": "What kind of answer the field takes. `select` takes one of `options`, `multi_select` a list of them, `date` an ISO date (YYYY-MM-DD), `file` a pre-uploaded file id (POST /v1/files, purpose additional_document)."
          },
          "required": {
            "type": "boolean"
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Allowed values for select / multi_select."
          },
          "guidance": {
            "type": "string",
            "description": "Longer explanation of what is being asked."
          },
          "help": {
            "type": "string",
            "description": "Short helper text under the input."
          },
          "note": {
            "type": "string",
            "description": "A caution shown near the field."
          },
          "placeholder": {
            "type": "string"
          },
          "info_points": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "conditional": {
            "$ref": "#/components/schemas/FieldConditional"
          },
          "validation": {
            "$ref": "#/components/schemas/FieldValidation"
          },
          "file": {
            "$ref": "#/components/schemas/FieldFileRule"
          },
          "group": {
            "type": "string",
            "description": "A stable id tying fields that belong together into one section - the generic shape a repeating block takes, such as one owner's details or one document set. Render every field sharing a `group` under a single heading and in the order they appear. Absent means a standalone field. Keys stay unique across the whole form, so `group` is only how you lay the fields out, never how you read or submit their values.",
            "example": "owner_1"
          },
          "group_label": {
            "type": "string",
            "description": "The heading to show for a field's `group`, for example the owner's name. Present on the fields of a group, readable from any of them.",
            "example": "Ada Lovelace"
          }
        }
      },
      "ServiceOrderForm": {
        "type": "object",
        "description": "The form the order's current fulfilment step is waiting on.",
        "required": [
          "fields"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "warning": {
            "type": "string",
            "description": "A caution to show above the form."
          },
          "fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceFormFieldDef"
            }
          }
        }
      },
      "ServiceOrderQuote": {
        "type": "object",
        "description": "The negotiated-price lifecycle on a product priced per order (for example, catch-up bookkeeping). `pending` until Clemta reviews the work and sets the amount, `quoted` while the price waits for your `accept_quote`, `accepted` once you took it and the charge landed. Nothing is billed before acceptance.",
        "required": [
          "state"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "pending",
              "quoted",
              "accepted"
            ]
          },
          "unit_amount": {
            "type": "integer",
            "format": "int64",
            "description": "The Clemta-set partner price, in the currency's smallest unit. Absent while pending."
          },
          "currency": {
            "type": "string"
          },
          "quoted_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Accept before this moment. A lapsed quote refuses acceptance, and Clemta re-prices on request."
          },
          "accepted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrderFee": {
        "type": "object",
        "required": [
          "kind",
          "unit_amount"
        ],
        "description": "One pass-through charge riding a service order, at the amount resolved when the order was made.",
        "properties": {
          "kind": {
            "type": "string",
            "description": "What the line is - state_fee, processing_fee or government_fee.",
            "example": "state_fee"
          },
          "unit_amount": {
            "type": "integer",
            "format": "int64",
            "description": "The amount in the currency's smallest unit.",
            "example": 30000
          },
          "currency": {
            "type": "string",
            "example": "usd"
          }
        }
      },
      "File": {
        "type": "object",
        "description": "A file: either a document Clemta published on one of your companies (`source: operations` - Articles, an EIN letter, a filed form - download the bytes from the content endpoint) or one you uploaded (`source: upload` - write-only, attach it by id). Nothing about storage is ever exposed - no URLs, no keys. Uploaded contents cannot be read back.",
        "required": [
          "object",
          "id",
          "name",
          "livemode",
          "created_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "file"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "pattern": "^file_[0-9A-Za-z]{22}$",
            "example": "file_0346sFPEvSkJvY8vt14NNw"
          },
          "company": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$",
            "description": "The company this document belongs to. Absent on an upload not yet attached."
          },
          "name": {
            "type": "string",
            "description": "The document's filename, extension included.",
            "example": "Articles_of_Incorporation.pdf"
          },
          "content_type": {
            "type": "string",
            "example": "application/pdf"
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Size in bytes, when known."
          },
          "purpose": {
            "type": "string",
            "enum": [
              "identity_document",
              "formation_document",
              "additional_document",
              "tax_form_1099",
              "business_logo",
              "business_icon"
            ],
            "description": "What an uploaded file is for. Absent on documents Clemta published."
          },
          "source": {
            "type": "string",
            "enum": [
              "operations",
              "upload"
            ],
            "description": "Who put the file here. `operations` - a deliverable we published, its bytes downloadable from the content endpoint. `upload` - you sent it (POST /v1/files), write-only: reference it by id, its contents can never be read back."
          },
          "kind": {
            "type": "string",
            "enum": [
              "formation_document",
              "ein_letter",
              "ss4",
              "w7",
              "ps1583",
              "governing_document",
              "good_standing_certificate",
              "signed_document",
              "form_attachment",
              "other"
            ],
            "description": "What a document we published is. `form_attachment` is a file you submitted on a service order form, coming back as a company document. `signed_document` is a completed e-signature. `other` covers anything not classified. Absent on your own uploads, which carry `purpose` instead.",
            "example": "ein_letter"
          },
          "service_order": {
            "type": "string",
            "pattern": "^so_[0-9A-Za-z]{22}$",
            "description": "The service order this document was delivered on, when it belongs to one. Absent on documents published on the company in general.",
            "example": "so_0346sFPEvSkJvY8vt14NNw"
          },
          "url": {
            "type": "string",
            "description": "Where the file's contents can be downloaded, with your API key. Present only when the purpose allows downloading - Clemta-published deliverables, never your own uploads."
          },
          "consumed": {
            "type": "boolean",
            "description": "True once an upload has been attached. Uploads are single-use."
          },
          "livemode": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ServiceOrder": {
        "type": "object",
        "description": "One product ordered on a company. Billed to you when created (or at each period end for arrears products). Reversed by a credit if cancelled before fulfilment starts. An active recurring order can be cancelled to stop renewing at the period end.",
        "required": [
          "object",
          "id",
          "company",
          "product_key",
          "status",
          "unit_amount",
          "currency",
          "created_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "service_order"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "pattern": "^so_[0-9A-Za-z]{22}$",
            "example": "so_0346sFPEvSkJvY8vt14NNw"
          },
          "company": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$",
            "description": "The company this order is on."
          },
          "product_key": {
            "type": "string",
            "example": "ein"
          },
          "interval": {
            "type": "string",
            "enum": [
              "one_time",
              "monthly",
              "yearly"
            ],
            "description": "Billing cadence - one_time, or recurring monthly/yearly."
          },
          "status": {
            "type": "string",
            "enum": [
              "received",
              "quote_pending",
              "in_progress",
              "requires_action",
              "completed",
              "canceled"
            ],
            "description": "Fulfilment status, derived from where Clemta has the order: `received` until fulfilment starts (a cancellable state), `quote_pending` while a priced-by-quote product waits for the price and your acceptance (also cancellable - cancelling declines the quote), `in_progress` while Clemta works, `requires_action` while the current step waits on a form from you or your customer (an open `form` requirement says which), `completed` once the final step is reached (`completed_at` is set and `service_order.completed` fires, and the order reopens if Clemta moves it back off its last step), and `canceled`."
          },
          "options": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "The variant choices this order was placed with (option key -\u003e value).",
            "example": {
              "llc_members": "multi_member"
            }
          },
          "form_required": {
            "type": "boolean",
            "description": "True when fulfilment needs a form from the customer (e.g. an ITIN or BOI service). Known once the order reaches fulfilment."
          },
          "workflow_status": {
            "type": "string",
            "description": "The live fulfilment step (e.g. \"Application In Progress\", \"Signature Request\"). Present once the order is being fulfilled."
          },
          "form": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ServiceOrderForm"
              }
            ],
            "description": "The form the current step is waiting on, when `form_required` is true - the fields to submit next via the form endpoint. Present on the single-order view."
          },
          "unit_amount": {
            "type": "integer",
            "format": "int64",
            "description": "The partner price you were billed, in the currency's smallest unit (cents).",
            "example": 7900
          },
          "currency": {
            "type": "string",
            "example": "usd"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "quote": {
            "$ref": "#/components/schemas/ServiceOrderQuote"
          },
          "shareholder": {
            "type": "string",
            "description": "The company owner this order is for (products ordered per owner, e.g. an ITIN)."
          },
          "outcome": {
            "type": "string",
            "description": "How a completed order ended, where completion alone does not say - a bank application's approved or declined, a good-standing check's not eligible. Recorded by Clemta. A decline is a delivered service, not a credit. Absent while the work runs and on orders whose completion is the whole answer."
          },
          "included_in": {
            "type": "string",
            "description": "Present when this order was attached by a bundle order (the formation's included services) - it names the bundle product. Included orders bill nothing of their own. A paid option choice bills only the difference."
          },
          "fees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderFee"
            },
            "description": "Pass-through lines this order carried beside `unit_amount` - the state's own charge and the processing fee, frozen at their order-time amounts. Each appears as its own line on your statement."
          },
          "next_renewal_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the next period bills (for a product billed in arrears, the end of the running period). Only on recurring orders. Absent once renewals end."
          },
          "renewal_cancel_requested_at": {
            "type": "string",
            "format": "date-time",
            "description": "When you requested cancellation. The request awaits a Clemta decision - renewals keep billing until it is approved. You hear the outcome as `service_order.renewal_canceled` or `service_order.renewal_cancel_denied`."
          },
          "renewal_canceled_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the cancellation was approved. The order stops billing at `renewal_ends_at`. Fulfilment status is unaffected."
          },
          "renewal_ends_at": {
            "type": "string",
            "format": "date-time",
            "description": "The period end the service runs to after a renewal cancel. An arrears product still bills this period at that moment, then stops."
          },
          "canceled_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the order first reached `completed`. `service_order.completed` announces this moment, and it does not change afterward."
          },
          "files": {
            "type": "array",
            "readOnly": true,
            "description": "The documents delivered on this order, newest first. Present only when requested with `expand[]=files`, and never in webhook payloads.",
            "items": {
              "$ref": "#/components/schemas/File"
            }
          }
        }
      },
      "RequirementSigner": {
        "type": "object",
        "description": "One party on a signature requirement. A document may need several signatures. Each signer gets their own hosted signing session and signs independently, and the requirement resolves only once the last of them completes.",
        "required": [
          "ref",
          "status"
        ],
        "properties": {
          "ref": {
            "type": "string",
            "pattern": "^sgr_[0-9A-Za-z]{22}$",
            "description": "The signer's stable handle. Supply a deferred (name-only) signer's email by this ref on POST /v1/companies/{id}/signature-signers."
          },
          "email": {
            "type": "string",
            "description": "The signer's email. Absent while status is `pending_email` - a name-only signer whose email you still owe."
          },
          "name": {
            "type": "string",
            "description": "The signer's display name."
          },
          "person": {
            "type": "string",
            "pattern": "^(sh|off)_[0-9A-Za-z]{22}$",
            "description": "The company shareholder (`sh_`) or officer (`off_`) this signer is, when the signer was picked from the company roster. Absent for a signer added as an outside party."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending_email",
              "pending",
              "viewed",
              "signed",
              "declined"
            ],
            "description": "Where this signer is: `pending_email` (no email yet - supply it), `pending` (email set, not opened), `viewed` (opened or started), `signed` (completed their part), `declined` (refused - which cancels the whole requirement)."
          },
          "viewed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When this signer first opened the document."
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "description": "When this signer began filling the document."
          },
          "signed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When this signer completed their part."
          },
          "declined_at": {
            "type": "string",
            "format": "date-time",
            "description": "When this signer declined."
          }
        }
      },
      "ServiceFormField": {
        "type": "object",
        "description": "One answer to a service order's current form step.",
        "required": [
          "value"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "The field key from the form schema, when it has one."
          },
          "field_name": {
            "type": "string",
            "description": "The field's label from the form schema."
          },
          "value": {
            "description": "The answer - a string, number, or boolean. A file field's value is a pre-uploaded file id (POST /v1/files, purpose additional_document)."
          }
        }
      },
      "RequirementAttachment": {
        "type": "object",
        "description": "One file-field upload collected on a form requirement.",
        "required": [
          "filename"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "The form field key this file answers."
          },
          "field_name": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "content_type": {
            "type": "string"
          },
          "size": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "Requirement": {
        "type": "object",
        "description": "One thing needed from you or your customer: an owner's identity document, a service-order form, or something Clemta asked for (a company-name change, extra information). Fulfill it over the API, or mint a hosted link and hand fulfillment to your customer.",
        "required": [
          "object",
          "id",
          "company",
          "type",
          "status",
          "requested_by",
          "livemode",
          "created_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "requirement"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "pattern": "^rqmt_[0-9A-Za-z]{22}$",
            "example": "rqmt_0346sFPEvSkJvY8vt14NNw"
          },
          "company": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$",
            "description": "The company this requirement is on."
          },
          "service_order": {
            "type": "string",
            "pattern": "^so_[0-9A-Za-z]{22}$",
            "description": "The service order this requirement belongs to - a form requirement's own order, or the order a Clemta-opened information or document ask was scoped to."
          },
          "shareholder": {
            "type": "string",
            "pattern": "^sh_[0-9A-Za-z]{22}$",
            "description": "The owner a document requirement is about."
          },
          "purpose": {
            "type": "string",
            "enum": [
              "identity_document",
              "formation_document",
              "additional_document"
            ],
            "description": "On a `document` requirement: the file-policy purpose it collects under, which decides the accepted size, content types, page count and link lifetime (see the file upload guide's policy table)."
          },
          "type": {
            "type": "string",
            "enum": [
              "document",
              "form",
              "name_change",
              "information",
              "signature"
            ],
            "description": "What fulfills it. `document` - an identity document file. `form` - the current fulfilment step's answers. `name_change` - a new company name (a `name` value). `information` - free-form answers."
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "resolved",
              "canceled"
            ]
          },
          "requested_by": {
            "type": "string",
            "enum": [
              "system",
              "operations"
            ],
            "description": "Who opened it - the platform itself, or Clemta."
          },
          "document_name": {
            "type": "string",
            "description": "For a signature requirement - the name of the document awaiting signature."
          },
          "signers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RequirementSigner"
            },
            "description": "For a signature requirement - every party that must sign, with each one's progress. The requirement resolves only when they have all signed."
          },
          "signature_sequential": {
            "type": "boolean",
            "description": "For a signature requirement - true when the parties sign in the order of the `signers` array (each becomes able to sign only once the one before them has). Absent or false means everyone signs in parallel."
          },
          "message": {
            "type": "string",
            "description": "Why it was opened, in words you can show your customer."
          },
          "cancel_reason": {
            "type": "string",
            "description": "On a canceled requirement - why it closed without being fulfilled: a signer's decline reason, or Clemta withdrawing the ask. Safe to show your customer."
          },
          "form": {
            "$ref": "#/components/schemas/ServiceOrderForm",
            "description": "For an OPEN `form` requirement: the fields to collect, read live from the fulfilment workflow."
          },
          "response": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceFormField"
            },
            "description": "What fulfilled it (absent for documents)."
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RequirementAttachment"
            },
            "description": "A form requirement's file-field uploads collected so far. Forwarded together with the values when the form is fulfilled."
          },
          "livemode": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "resolved_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Relationship": {
        "type": "object",
        "additionalProperties": false,
        "description": "The owner's relationship to the company - role, stake, and standing.",
        "properties": {
          "title": {
            "type": "string",
            "enum": [
              "sole_owner",
              "product_manager",
              "project_manager",
              "software_engineer",
              "data_analyst",
              "ux_designer",
              "ui_designer",
              "other"
            ],
            "description": "The owner's role, as an API token - the platform's owner position list. Officer-sounding roles (CEO, CFO, ...) are not owner titles. They belong on the officer roster. Use `other` with `custom_title` for any role outside this list."
          },
          "custom_title": {
            "type": "string",
            "maxLength": 120,
            "pattern": "^[A-Za-z0-9 \u0026.,:;'#-]+$",
            "description": "The custom role name. Required when `title` is `other`, rejected otherwise."
          },
          "percent_ownership": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100,
            "description": "Must be above 0 for an individual or company owner."
          },
          "representative": {
            "type": "boolean",
            "description": "The primary owner authorized to act for the company. With more than one owner, mark exactly one as the representative. A single owner is taken as the representative automatically, so this can be omitted then."
          },
          "director": {
            "type": "boolean"
          }
        }
      },
      "Document": {
        "type": "object",
        "required": [
          "status"
        ],
        "description": "The state of an owner's identity document.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "required",
              "received",
              "not_required"
            ],
            "description": "`required` until the owner's identity document is uploaded, then `received`. For a company owner the document is its authorized representative's. `not_required` only for an option pool - a share bucket with nobody behind it."
          }
        }
      },
      "Shareholder": {
        "type": "object",
        "required": [
          "object",
          "id",
          "type",
          "relationship",
          "document"
        ],
        "description": "A company owner.",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "shareholder"
            ]
          },
          "id": {
            "type": "string",
            "pattern": "^sh_[0-9A-Za-z]{22}$"
          },
          "type": {
            "type": "string",
            "enum": [
              "individual",
              "company",
              "option_pool"
            ]
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "representative_name": {
            "type": "string",
            "maxLength": 255,
            "description": "The natural person acting for a company owner. Required for a company owner."
          },
          "email": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "phone_country": {
            "type": "string",
            "description": "The phone's ISO 3166 alpha-2 country code."
          },
          "tax_id_type": {
            "type": "string",
            "enum": [
              "ssn",
              "itin",
              "ein"
            ]
          },
          "relationship": {
            "$ref": "#/components/schemas/Relationship"
          },
          "document": {
            "$ref": "#/components/schemas/Document"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "OfficerRole": {
        "type": "string",
        "enum": [
          "member",
          "managing_member",
          "manager",
          "director",
          "president",
          "ceo",
          "secretary",
          "treasurer",
          "cfo",
          "vice_president"
        ],
        "description": "A position on the company's management roster. The catalogue is fixed per entity type. An LLC holds `member`, `managing_member` or `manager`. A C-Corp holds `director`, `president`, `ceo`, `secretary`, `treasurer`, `cfo` or `vice_president`. A director is simply an officer holding the `director` role. `member` and `managing_member` are owner-only - only a shareholder can hold them. A member-managed LLC has no `manager`, and a manager-managed LLC has no `managing_member` - there an owner holding `manager` is the managing member. A C-Corp must keep at least one director, and a manager-managed LLC at least one manager. For any wording outside these positions use the free-text `title`."
      },
      "CompanyOfficer": {
        "type": "object",
        "description": "One row of the company's management roster: a person and the positions they hold. A director is an officer holding the `director` role - there is no separate directors list. An officer who is also an owner carries the `shareholder` id of the owner they are. A non-owner officer (a hired director or officer who holds no shares) carries none.",
        "required": [
          "object",
          "id",
          "roles"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "officer"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "pattern": "^off_[0-9A-Za-z]{22}$",
            "example": "off_0346sFPEvSkJvY8vt14NNw"
          },
          "shareholder": {
            "type": "string",
            "pattern": "^sh_[0-9A-Za-z]{22}$",
            "description": "The owner this officer is, when they hold shares. Absent for a non-owner officer."
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "description": "A free-text position label Clemta may keep alongside the roles."
          },
          "roles": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/OfficerRole"
            },
            "description": "The positions this person holds, entity-gated."
          },
          "source": {
            "type": "string",
            "enum": [
              "onboarding",
              "ops"
            ],
            "description": "Who put the row on the roster - the customer's onboarding or Clemta."
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "Company": {
        "type": "object",
        "required": [
          "object",
          "id",
          "account_id",
          "livemode",
          "name",
          "state",
          "entity_type",
          "status",
          "verification",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false,
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "company"
            ],
            "description": "Entity name. Identifies this object when it arrives without its URL - nested under an `expand[]`, inside an event payload, or in a webhook."
          },
          "id": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$",
            "description": "Identifier of the company.",
            "example": "cmp_0346sFPEvSkJvY8vt14NNw"
          },
          "external_id": {
            "type": "string",
            "description": "Your own identifier for this company, unique across your companies."
          },
          "account_id": {
            "type": "string",
            "pattern": "^acct_[0-9A-Za-z]{22}$",
            "description": "The account (the incorporator) this company was created under. Expand `account` to embed the full object.",
            "example": "acct_0346sFPEvSkJvY8vt14NNw"
          },
          "account": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Account"
              }
            ],
            "description": "The full account this company was created under. Present only when requested with `expand[]=account`."
          },
          "livemode": {
            "type": "boolean",
            "description": "False for a company created with a test key. A test company is a sandbox simulation - it never reaches fulfillment or billing."
          },
          "name": {
            "type": "string",
            "description": "Legal name of the company."
          },
          "state": {
            "$ref": "#/components/schemas/StateCode"
          },
          "entity_type": {
            "type": "string",
            "enum": [
              "llc",
              "c_corp"
            ],
            "description": "Entity type being formed.",
            "example": "llc"
          },
          "ending": {
            "type": "string"
          },
          "industry": {
            "type": "string"
          },
          "industry_description": {
            "type": "string",
            "description": "Free-text description of the business, present when industry is `other`."
          },
          "custom_industry": {
            "type": "string",
            "description": "Short name of the custom industry, present when industry is `other`."
          },
          "timezone": {
            "type": "string",
            "description": "The company's IANA time zone."
          },
          "name_style": {
            "type": "string",
            "enum": [
              "plain",
              "comma"
            ],
            "description": "How the legal name renders around the ending."
          },
          "legal_name": {
            "type": "string",
            "readOnly": true,
            "description": "The rendered legal name - `name`, the `name_style` separator, and the `ending` (\"Acme, LLC\")."
          },
          "owner_privacy": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ],
            "description": "Whether the owners are kept off the public filing. Choosable only in DE, NV, WY, NM."
          },
          "pre_existing": {
            "type": "boolean",
            "description": "True when the company already existed before it was brought to Clemta. False when Clemta forms it."
          },
          "status": {
            "type": "string",
            "enum": [
              "requires_information",
              "in_progress",
              "active",
              "cancelled",
              "dissolved"
            ],
            "description": "Lifecycle status. A company starts in requires_information while it waits for its owners' identity documents. It moves to in_progress once every required document is present and it is submitted for formation, and to active once fulfilled."
          },
          "ein": {
            "type": "string",
            "description": "The federal tax id, once the IRS has issued it. Fires `company.ein.assigned` when it lands."
          },
          "verified_at": {
            "type": "string",
            "format": "date-time",
            "description": "When every owner's identity document was in and the company was ready for formation. `company.verified` announces this moment, and it does not change afterward."
          },
          "dissolved_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the company was dissolved. Terminal: the company's status is `dissolved` from that moment, every recurring service stopped renewing, open requirements were closed, and nothing further can be ordered. `company.dissolved` announces this moment, and it does not change afterward."
          },
          "incorporated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the company was marked incorporated in Clemta - the moment `company.incorporated` fires. It can differ from `incorporation_date`, the legal formation date the state assigned."
          },
          "ein_assigned_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the EIN was assigned. `company.ein.assigned` announces this moment, and it does not change afterward."
          },
          "stage": {
            "type": "string",
            "enum": [
              "preparing_documents",
              "documents_generated",
              "signature_requested",
              "submitted_to_state",
              "name_conflict",
              "incorporated",
              "closed"
            ],
            "description": "The fine-grained formation step under `status` - where formation stands right now. Changes fire `company.status.changed`. Reaching `incorporated` also fires `company.incorporated`."
          },
          "incorporation_date": {
            "type": "string",
            "description": "The legal formation date the state assigned, recorded from the formation document (for a `pre_existing` company, the one uploaded through its requirement). It can differ from `incorporated_at`, which is when Clemta marked the company incorporated. Never an input. `company.updated` announces changes."
          },
          "address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "The company's legal address, maintained by Clemta."
          },
          "foreign_qualifications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ForeignQualification"
            },
            "description": "States the company is registered in beside its formation state."
          },
          "entitlements": {
            "$ref": "#/components/schemas/CompanyEntitlements"
          },
          "open_requirements": {
            "type": "integer",
            "format": "int64",
            "readOnly": true,
            "description": "How many requirements currently stand open on this company - \"is anything waiting on you\" in one number, without touching `status`. Derived at read time on API responses. Webhook `data.object` snapshots omit it."
          },
          "service_orders": {
            "type": "array",
            "readOnly": true,
            "items": {
              "$ref": "#/components/schemas/ServiceOrder"
            },
            "description": "Every service order on the company, newest first, embedded when the request carries `expand[]=service_orders` - including the mandatory products a create attached automatically. The same rows `GET /companies/{id}/service-orders` lists."
          },
          "requirements": {
            "type": "array",
            "readOnly": true,
            "items": {
              "$ref": "#/components/schemas/Requirement"
            },
            "description": "The open requirements themselves, embedded when the request carries `expand[]=requirements` - the list behind `open_requirements`. Resolved history stays on `GET /companies/{id}/requirements`."
          },
          "verification": {
            "type": "string",
            "enum": [
              "pending",
              "verified"
            ],
            "description": "Whether the company's owners have submitted the identity documents needed to file. `verified_at` records when. State filings wait for it."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the company was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the company was last modified. Also written to the `Last-Modified` response header on a single-company fetch, so a conditional `If-Modified-Since` request can be answered `304 Not Modified`."
          },
          "shareholders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Shareholder"
            },
            "description": "The company's owners. Collect a missing identity document by attaching an uploaded file (`passport`) or by creating a verification session for the owner."
          },
          "officers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompanyOfficer"
            },
            "description": "The management roster - everyone who holds a position. A director is an officer holding the `director` role. There is no separate directors list. Includes officers who are not owners. Set at company creation, and kept current as the roster changes."
          },
          "management_type": {
            "type": "string",
            "enum": [
              "member_managed",
              "manager_managed"
            ],
            "description": "LLC only - whether the company is member-managed or manager-managed."
          },
          "officers_settled": {
            "type": "boolean",
            "description": "Whether the officer roster is final. When true with an empty `officers`, the company has no officers by design, not a roster still being collected."
          },
          "metadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": true,
            "description": "Your own key-value pairs, stored and returned verbatim. Clemta never reads them."
          }
        }
      },
      "CompanyList": {
        "type": "object",
        "required": [
          "object",
          "page",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ],
            "description": "Entity name."
          },
          "page": {
            "$ref": "#/components/schemas/Page"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Company"
            }
          }
        }
      },
      "CreateShareholderBody": {
        "type": "object",
        "required": [
          "type",
          "relationship"
        ],
        "additionalProperties": false,
        "description": "A company owner. An individual needs first_name and last_name. A company needs name and representative_name. A tax_id is optional. When present, its tax_id_type must be ssn or itin for an individual and ein for a company. Identity documents are never sent here - each individual owner uploads theirs through the upload link returned on the company.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "individual",
              "company",
              "option_pool"
            ]
          },
          "first_name": {
            "type": "string",
            "maxLength": 255,
            "pattern": "^[A-Za-z ]+$",
            "description": "Required for an individual. English letters and spaces only."
          },
          "last_name": {
            "type": "string",
            "maxLength": 255,
            "pattern": "^[A-Za-z ]+$",
            "description": "Required for an individual. English letters and spaces only."
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "pattern": "^[A-Za-z0-9 \u0026.,-]+$",
            "description": "Legal name. Required for a company owner."
          },
          "representative_name": {
            "type": "string",
            "maxLength": 255,
            "pattern": "^[A-Za-z0-9 \u0026.,-]+$",
            "description": "The natural person acting for a company owner. Required for a company owner."
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 255
          },
          "phone": {
            "type": "string",
            "maxLength": 32
          },
          "phone_country": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$",
            "description": "The phone's ISO 3166 alpha-2 country code, e.g. `us`."
          },
          "tax_id": {
            "type": "string",
            "maxLength": 32,
            "description": "SSN or ITIN for an individual, EIN for a company. Optional. Write-only, never returned."
          },
          "tax_id_type": {
            "type": "string",
            "enum": [
              "ssn",
              "itin",
              "ein"
            ]
          },
          "relationship": {
            "$ref": "#/components/schemas/Relationship"
          },
          "address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "The owner's residential address. Required for an individual."
          },
          "passport": {
            "type": "string",
            "pattern": "^file_[0-9A-Za-z]{22}$",
            "description": "The owner's identity document as an uploaded file id (POST /v1/files, purpose `identity_document`). With it the owner arrives complete - no upload link is minted. Single-use."
          }
        }
      },
      "CreateOfficerBody": {
        "type": "object",
        "description": "A management-roster row to seat at company creation. A director is an officer holding role `director`. An officer whose `email` matches a shareholder's is seated as that owner - its identity then lives on the shareholder - so it needs no name of its own. A non-owner officer (one matching no shareholder) needs a name.",
        "required": [
          "roles"
        ],
        "properties": {
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "description": "Contact, and - when it matches a shareholder's email - the key that seats this officer as that owner."
          },
          "title": {
            "type": "string",
            "description": "A free-text position label kept alongside the roles."
          },
          "roles": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/OfficerRole"
            },
            "description": "The positions this person holds, entity-gated (LLC vs C-Corp catalogues)."
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "CreateCompanyBody": {
        "type": "object",
        "required": [
          "name",
          "state",
          "entity_type"
        ],
        "additionalProperties": false,
        "properties": {
          "external_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Your own identifier for this company. Must be unique across your companies. Reusing one is rejected. Use `Idempotency-Key` to retry safely."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^[A-Za-z0-9 \u0026-]+$",
            "description": "Legal name of the company to form, without the ending. IRS naming rules apply: letters, numbers, spaces, hyphen (-) and ampersand (\u0026) only, and the name must not start with \"The\". The ending (\"LLC\", \"Inc.\") is the separate `ending` field. A name already registered with us in the same state is refused up front (`invalid_request`). The state registry remains the final authority - a conflict it finds later arrives as a `name_change` requirement."
          },
          "name_style": {
            "type": "string",
            "enum": [
              "plain",
              "comma"
            ],
            "default": "plain",
            "description": "How the legal name renders around the ending: `plain` (\"Acme LLC\") or `comma` (\"Acme, LLC\"). The rendered result is the read-only `legal_name` on the company."
          },
          "owner_privacy": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ],
            "default": "public",
            "description": "Whether the owners are kept off the public filing. `private` is available only in the states that offer it - DE, NV, WY, NM - and is rejected elsewhere."
          },
          "pre_existing": {
            "type": "boolean",
            "default": false,
            "description": "Did the company exist before you brought it here? `false` (the default): Clemta forms it, and the formation is billed. `true`: an already-formed company you are bringing in to offer services on - no formation is billed. Products marked `required_for` the matching set (`formation` or `existing`) attach automatically."
          },
          "state": {
            "$ref": "#/components/schemas/StateCode"
          },
          "entity_type": {
            "type": "string",
            "enum": [
              "llc",
              "c_corp"
            ],
            "description": "Entity type to form.",
            "example": "llc"
          },
          "ending": {
            "type": "string",
            "enum": [
              "llc",
              "l_l_c",
              "limited_liability_company",
              "inc",
              "incorporated",
              "co",
              "corp",
              "corporation"
            ],
            "description": "The company name suffix, as an API token. The rendered legal text is `llc` -\u003e \"LLC\", `l_l_c` -\u003e \"L.L.C.\", `limited_liability_company` -\u003e \"Limited Liability Company\", `inc` -\u003e \"Inc.\", `incorporated` -\u003e \"Incorporated\", `co` -\u003e \"Co.\", `corp` -\u003e \"Corp\", `corporation` -\u003e \"Corporation\" (see `legal_name` on the company). Must match the entity type - the first three are LLC endings, the rest C-Corp endings."
          },
          "industry": {
            "type": "string",
            "enum": [
              "accounting",
              "advertising",
              "agriculture",
              "art",
              "theater",
              "beauty_and_cosmetic_services",
              "biotech",
              "business_management",
              "cleaning_services",
              "construction",
              "consulting",
              "design",
              "e_commerce",
              "education",
              "entertainment",
              "financial_services",
              "fitness",
              "food",
              "hardware",
              "health_services",
              "insurance",
              "investment",
              "legal",
              "logistics",
              "marketing",
              "marketplace",
              "real_estate",
              "recruiting",
              "research",
              "retail_wholesale",
              "shipping_warehousing",
              "support_services",
              "software",
              "technology",
              "transportation",
              "other"
            ],
            "description": "The company's primary industry, from the platform's standard industry catalog, as API tokens. `other` requires `custom_industry` and `industry_description`."
          },
          "ein": {
            "type": "string",
            "maxLength": 12,
            "pattern": "^[0-9]{2}-?[0-9]{7}$",
            "description": "The company's EIN, for a `pre_existing` company that already holds one. Stored formatted `12-3456789`. `company.ein.assigned` does not fire for a value supplied here. Rejected when Clemta forms the company - the EIN is issued during formation and appears on the company once assigned (`company.ein.assigned`)."
          },
          "address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "The company's legal address. Required for a `pre_existing` company - an existing company has one by definition. Rejected when Clemta forms the company - Clemta records the address during formation and it appears on the company then."
          },
          "foreign_qualifications": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/ForeignQualification"
            },
            "description": "States the company is registered in beside its formation state, for a `pre_existing` company. Each names a different state than the formation state. Rejected when Clemta forms the company."
          },
          "industry_description": {
            "type": "string",
            "maxLength": 500,
            "description": "A free-text description of the business. Required when `industry` is `other`, rejected otherwise."
          },
          "custom_industry": {
            "type": "string",
            "maxLength": 120,
            "description": "The short name of the custom industry. Required when `industry` is `other`, rejected otherwise."
          },
          "timezone": {
            "type": "string",
            "maxLength": 64,
            "description": "IANA time zone for the company (e.g. `America/Chicago`). Defaults to the formation state's primary zone."
          },
          "authorized_shares": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "description": "Total authorized shares. Required for a c_corp. Not accepted for an llc, which is issued a fixed 100 membership units."
          },
          "par_value": {
            "type": "number",
            "minimum": 0,
            "description": "Par value per share, in dollars. Required for a c_corp. Not accepted for an llc."
          },
          "account": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CreateAccountBody"
              }
            ],
            "description": "Account details to create the incorporator alongside this company, when you have not created one yet. Omit it and set the `Clemta-Account` header to create the company under an account that already exists. Pass one or the other, never both. Reusing an account `external_id` returns the account already on file instead of creating a duplicate."
          },
          "shareholders": {
            "type": "array",
            "maxItems": 25,
            "items": {
              "$ref": "#/components/schemas/CreateShareholderBody"
            },
            "description": "The company's owners, as structured data. Optional at create - owners can also be collected later through the embedded form. Identity documents are never sent here. Upload them through the Files API and reference them by `passport`. When present, exactly one owner must be the main incorporator."
          },
          "officers": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/CreateOfficerBody"
            },
            "description": "The management roster - everyone who holds a position, each with their roles. A director is an officer holding role `director`. There is no separate directors list. Optional: when omitted, a shareholder's `relationship.director` flag seats directors. When given, this list is the roster. An officer whose `email` matches a shareholder's is seated as that owner."
          },
          "management_type": {
            "type": "string",
            "enum": [
              "member_managed",
              "manager_managed"
            ],
            "description": "LLC only - whether the company is member-managed or manager-managed."
          },
          "services": {
            "type": "array",
            "maxItems": 25,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9_]{1,48}$"
            },
            "description": "Products to order on the company at creation, by key - the same keys `GET /products` lists. Each is attached as a service order and billed to you at your partner price, alongside the formation. Formation itself is implied by creating the company and need not be listed here.",
            "example": [
              "ein",
              "registered_agent"
            ]
          },
          "service_options": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "description": "Variant choices for the services attached at creation, keyed by product key - the listed ones, the mandatory ones, the formation itself (`{\"formation\": {\"turnaround\": \"expedited\"}}` is how expedited filing is chosen, and registration is the only moment it can be), and the formation bundle's included services. A key naming a product that is not being attached is refused.",
            "example": {
              "ein": {
                "turnaround": "expedited"
              }
            }
          },
          "metadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": true,
            "description": "Your own key-value pairs, stored and returned verbatim."
          }
        }
      },
      "UpdateCompanyBody": {
        "type": "object",
        "additionalProperties": false,
        "description": "Sparse update: only the fields you send change, everything else stays as it is. While the company is `requires_information` (not yet handed to Clemta) the create-time details can still be corrected. After hand-off only `timezone`, `owner_privacy`, `foreign_qualifications` and `metadata` remain updatable - everything else is Clemta's to change from there. `entity_type`, `state` and `pre_existing` are never updatable: they price the formation - cancel the company and create it again instead.",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^[A-Za-z0-9 \u0026-]+$",
            "description": "New legal name (IRS charset, no leading \"The\"). Before hand-off only."
          },
          "ending": {
            "type": "string",
            "enum": [
              "llc",
              "l_l_c",
              "limited_liability_company",
              "inc",
              "incorporated",
              "co",
              "corp",
              "corporation"
            ],
            "description": "New name suffix token, must match the entity type. Before hand-off only."
          },
          "name_style": {
            "type": "string",
            "enum": [
              "plain",
              "comma"
            ],
            "description": "How the legal name renders around the ending. Before hand-off only."
          },
          "owner_privacy": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ],
            "description": "Whether the owners are kept off the public filing. `private` only in DE, NV, WY, NM. Updatable before and after hand-off."
          },
          "industry": {
            "type": "string",
            "enum": [
              "accounting",
              "advertising",
              "agriculture",
              "art",
              "theater",
              "beauty_and_cosmetic_services",
              "biotech",
              "business_management",
              "cleaning_services",
              "construction",
              "consulting",
              "design",
              "e_commerce",
              "education",
              "entertainment",
              "financial_services",
              "fitness",
              "food",
              "hardware",
              "health_services",
              "insurance",
              "investment",
              "legal",
              "logistics",
              "marketing",
              "marketplace",
              "real_estate",
              "recruiting",
              "research",
              "retail_wholesale",
              "shipping_warehousing",
              "support_services",
              "software",
              "technology",
              "transportation",
              "other"
            ],
            "description": "One of the platform catalog's tokens. Before hand-off only."
          },
          "industry_description": {
            "type": "string",
            "maxLength": 500,
            "description": "Required alongside `industry: other`, refused otherwise. Before hand-off only."
          },
          "custom_industry": {
            "type": "string",
            "maxLength": 120,
            "description": "The short name of the custom industry. Required alongside `industry: other`, refused otherwise. Before hand-off only."
          },
          "authorized_shares": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "description": "c_corp only. Before hand-off only."
          },
          "par_value": {
            "type": "number",
            "minimum": 0,
            "description": "c_corp only. Before hand-off only."
          },
          "timezone": {
            "type": "string",
            "maxLength": 64,
            "description": "IANA time zone. Updatable before and after hand-off."
          },
          "ein": {
            "type": "string",
            "maxLength": 12,
            "pattern": "^[0-9]{2}-?[0-9]{7}$",
            "description": "For a `pre_existing` company only. Before hand-off only."
          },
          "address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "For a `pre_existing` company only. Before hand-off only."
          },
          "foreign_qualifications": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/ForeignQualification"
            },
            "description": "Replaces the full list. For a `pre_existing` company, updatable before and after hand-off. An empty array clears it."
          },
          "shareholders": {
            "type": "array",
            "maxItems": 25,
            "items": {
              "$ref": "#/components/schemas/CreateShareholderBody"
            },
            "description": "The company's owners. Send this to collect the owners a company was created without, or to correct the roster - before hand-off only. It REPLACES the whole roster and follows the same rules as at create: exactly one main incorporator, ownership totals 100 percent. An individual owner without a `passport` gets an identity-document requirement to fulfill later. An empty array clears the roster."
          },
          "metadata": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": true,
            "description": "Replaces the company's metadata with this set. Send the full map you want stored. An empty object clears it. Your own key-value pairs, returned verbatim."
          }
        }
      },
      "ServiceOrderList": {
        "type": "object",
        "description": "A company's service orders. Unpaginated - the set is small and bounded.",
        "required": [
          "object",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ],
            "description": "Entity name."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceOrder"
            }
          }
        }
      },
      "CreateServiceOrderBody": {
        "type": "object",
        "description": "Attach a product to a company. Idempotent - one order per product per company, unless the product's `repeat` policy allows more: then each instance (a tax year, a state, a bank, an owner, or simply the nth request) is its own order.",
        "required": [
          "product_key"
        ],
        "properties": {
          "product_key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "pattern": "^[a-z][a-z0-9_]{1,48}$",
            "description": "The product to order, by key. Must be an active product in your catalog.",
            "example": "ein"
          },
          "options": {
            "type": "object",
            "maxProperties": 10,
            "additionalProperties": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9_]{1,48}$"
            },
            "description": "Your choice for each of the product's `options` (key -\u003e value), as listed on `GET /products`. A required option that is missing, an unknown key, or an unknown value answers `400 invalid_request` with one `errors[]` entry per problem.",
            "example": {
              "llc_members": "multi_member"
            }
          },
          "shareholder": {
            "type": "string",
            "pattern": "^sh_[0-9A-Za-z]{22}$",
            "description": "The company owner this order is for. Required exactly when the product repeats per owner (`repeat: per_shareholder` - an ITIN application). Refused on every other product."
          },
          "form": {
            "type": "array",
            "maxItems": 100,
            "description": "Optionally answer the first form step in the same call - for services whose first step collects input (e.g. an EIN's SS-4 or an operating agreement's details), the order kicks off fully in one request.",
            "items": {
              "$ref": "#/components/schemas/ServiceFormField"
            }
          }
        }
      },
      "UpdateServiceOrderBody": {
        "type": "object",
        "description": "Two order actions share this endpoint: upgrading the order's options, and accepting a Clemta-set quote. Send exactly one of them.",
        "properties": {
          "options": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "The order's new variant choices, complete - the same shape the create call takes. Unchanged keys may be repeated. The change must not lower the price, and an option marked `fixed` in the catalog cannot change.",
            "example": {
              "turnaround": "expedited"
            }
          },
          "accept_quote": {
            "type": "boolean",
            "description": "Accept the Clemta-set price on a quote_pending order. The quoted amount becomes the order's price and is billed at that moment. Refused before a price exists or after `quote.expires_at`. Idempotent once accepted."
          }
        }
      },
      "ProductOptionValue": {
        "type": "object",
        "description": "One choice on a product option.",
        "required": [
          "value",
          "label"
        ],
        "properties": {
          "value": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{1,48}$",
            "description": "The value you send in `options`.",
            "example": "multi_member"
          },
          "label": {
            "type": "string",
            "example": "Multi-member LLC"
          },
          "available_when": {
            "type": "object",
            "additionalProperties": true,
            "description": "When present, this value may only be chosen for companies matching the condition - for example an expedited filing offered in certain states only. Choosing it elsewhere is refused naming the option."
          },
          "unit_amount": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "The partner price of the product when this value is chosen, in the currency's smallest unit. Absent means the product's own price applies. If Clemta set you an override on the product, the override applies whatever you choose.",
            "example": 24900
          },
          "quote": {
            "type": "boolean",
            "description": "When true, choosing this value prices the order per order rather than from a fixed amount: the order opens unbilled in `quote_pending`, Clemta sets the price, and billing happens when you accept it - while the option's other values carry their fixed prices. `unit_amount` is absent on a quoted value."
          }
        }
      },
      "ProductOption": {
        "type": "object",
        "description": "One variant axis of a product - a choice made at order time. Pass your choice as `options[\u003ckey\u003e] = \u003cvalue\u003e` when creating a service order.",
        "required": [
          "key",
          "label",
          "values"
        ],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{1,48}$",
            "description": "The option's identifier, the key you send in `options`.",
            "example": "llc_members"
          },
          "fixed": {
            "type": "boolean",
            "description": "A fixed option is chosen at order time and is never upgradable later. The options-upgrade endpoint refuses to change it."
          },
          "label": {
            "type": "string",
            "description": "Human-readable name of the choice.",
            "example": "LLC membership"
          },
          "required": {
            "type": "boolean",
            "description": "True when an order for this product must choose a value."
          },
          "values": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ProductOptionValue"
            }
          }
        }
      },
      "PriceRule": {
        "type": "object",
        "description": "One conditional price point. When `match` holds against the company the order is for, the order prices at `unit_amount` instead of the product default - rules are evaluated in order and the first match wins. The condition is answered by the company record itself, so there is nothing extra to send on the order.",
        "required": [
          "key",
          "match",
          "unit_amount"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Stable identifier of the rule.",
            "example": "de_filing"
          },
          "label": {
            "type": "string",
            "description": "Display name, when one is set.",
            "example": "Delaware filing"
          },
          "match": {
            "type": "object",
            "additionalProperties": true,
            "description": "Condition over the company attributes `entity_type`, `state`, `pre_existing` and `owners_count`, in query-operator form - a plain value means equality, `$in`, `$gte`, `$and`, `$or` and friends are supported.",
            "example": {
              "state": "DE"
            }
          },
          "unit_amount": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "Your price in the currency's smallest unit (cents) when the rule matches.",
            "example": 31500
          }
        }
      },
      "Product": {
        "type": "object",
        "description": "A product you can offer, priced at your partner rate.",
        "required": [
          "object",
          "key",
          "display_name",
          "unit_amount",
          "currency"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "product"
            ],
            "description": "Entity name."
          },
          "key": {
            "type": "string",
            "description": "The identifier you order by - pass it as `product_key` on a service order.",
            "example": "formation_llc"
          },
          "display_name": {
            "type": "string",
            "example": "Company Formation (LLC)"
          },
          "unit_amount": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "Your partner price in the currency's smallest unit (cents) - your override if you have one, otherwise the default.",
            "example": 14900
          },
          "currency": {
            "type": "string",
            "example": "usd"
          },
          "interval": {
            "type": "string",
            "enum": [
              "one_time",
              "monthly",
              "yearly"
            ],
            "description": "Billing cadence - one_time, or recurring monthly/yearly."
          },
          "trial_periods": {
            "type": "integer",
            "description": "How many opening billing intervals are free on this product - for example 1 on a yearly service whose first year is included, or 12 on a monthly fee that starts billing after a year. An order created for it carries no charge until the first paid period arrives. Absent or 0 means billing starts at creation."
          },
          "billing": {
            "type": "string",
            "enum": [
              "advance",
              "arrears"
            ],
            "description": "When a recurring period is billed. `advance` bills the first period at order creation and every later one at its start. `arrears` bills each period at its end instead - the order is created with no charge and the first invoice line lands one interval later. Absent means advance."
          },
          "includes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Products an order for this one attaches automatically at no extra charge - each appears as its own order marked `included_in`, with its own status and events. The formation's bundle (registered agent, business address, EIN, bank application) is the live case."
          },
          "description": {
            "type": "string",
            "description": "What the product is, expected timelines, and any disclaimers - shown to you verbatim. Carry the disclaimers into your own customer-facing copy (e.g. a business mailing address is not proof of physical presence, bank approval is the institution's decision)."
          },
          "quote": {
            "type": "boolean",
            "description": "Priced per order: the order opens unbilled in `quote_pending`, Clemta reviews the work and sets the price (`service_order.quoted`), and billing happens when you accept it. `unit_amount` on this product is indicative only. A quote product has no options to choose - `options` is omitted for it, because the price is set per order rather than by a variant."
          },
          "on_complete": {
            "type": "string",
            "description": "A company-level effect the order's completion fires. Today only `dissolve_company` - the dissolution product: completing it closes the company (terminal `dissolved` status, renewals ended, open requirements closed)."
          },
          "repeat": {
            "type": "string",
            "description": "The product's repeatability. Absent means one order per company. `per_order` means every purchase is its own instance. `per_option:\u003ckey\u003e` means one order per value of that option (a filing per tax_year, a registration per state). `per_shareholder` means one order per company owner, named by `shareholder` on the order."
          },
          "conflicts_with": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Products this one cannot be held together with - ordering it while the company holds one of these (or the same creation basket carries one) is refused."
          },
          "depends_on": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Products that must already be ordered on the company before this one can be - a missing prerequisite is refused naming the key."
          },
          "defer_first_charge": {
            "type": "string",
            "enum": [
              "first_anniversary"
            ],
            "description": "When present, an order created before the stated anchor bills nothing at creation: for first_anniversary the first charge lands one interval after the company's incorporation date. Ordered after the anniversary, it bills at creation as usual."
          },
          "pass_through_fees": {
            "type": "string",
            "enum": [
              "annual_state_filing",
              "trademark_government",
              "sales_tax_government",
              "amendment_government",
              "dissolution_government",
              "cogs_government"
            ],
            "description": "When present, an order for this product also bills government or state fee lines beside the product price, at the amounts current at order time. annual_state_filing adds the state's own annual report / franchise charge and the processing fee. The others add that filing's government fee. Each appears as its own line on your statement and on the order's `fees`."
          },
          "required_for": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "formation",
                "existing"
              ]
            },
            "description": "Which companies this product is mandatory on: `formation` (companies Clemta forms) and/or `existing` (pre-existing companies you bring in). Creating such a company attaches and bills it automatically - include it in your own pricing."
          },
          "options": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/ProductOption"
            },
            "description": "The product's variants, when it has any. Each is a choice made at order time. A `required` one must be sent in `options` on the service order."
          },
          "price_rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceRule"
            },
            "description": "Conditional amounts for this product, applied automatically from the company the order is for - nothing extra to send. Evaluated in order, first match wins. No match pays `unit_amount`."
          },
          "fulfillment": {
            "type": "string",
            "enum": [
              "workflow",
              "entitlement"
            ],
            "default": "workflow",
            "description": "What the fulfilment is. `workflow` - Clemta fulfils the order step by step, possibly asking for forms (follow `status` / requirements). `entitlement` - the order grants the company a right (a tax-filing credit, for instance) that is then exercised in the company's own flow. An entitlement order completes at provisioning and never asks for a form."
          },
          "available_when": {
            "type": "object",
            "additionalProperties": true,
            "description": "Who this product can be ordered to, as a match condition over the company attributes entity_type, state, pre_existing and owners_count. Empty or absent means every company. An order for a company outside it is refused.",
            "example": {
              "entity_type": "llc"
            }
          }
        }
      },
      "ProductList": {
        "type": "object",
        "description": "Your catalog. Unpaginated - the set is small and bounded.",
        "required": [
          "object",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ],
            "description": "Entity name."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          }
        }
      },
      "PricePreviewFee": {
        "type": "object",
        "description": "One prospective pass-through line - a government or state fee.",
        "required": [
          "kind",
          "unit_amount",
          "currency"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "description": "The fee's stable kind, the same value the order's `fees` carry.",
            "example": "state_fee"
          },
          "unit_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Today's amount in cents."
          },
          "currency": {
            "type": "string",
            "example": "usd"
          }
        }
      },
      "PricePreview": {
        "type": "object",
        "description": "Every line an order for this product COULD put on your statement, resolved for the stated company profile. Amounts are today's - the order resolves them again and freezes what it billed on the order's own `fees` - so treat this as an estimate, never a quote.",
        "required": [
          "object",
          "product_key",
          "unit_amount",
          "currency",
          "estimate"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "price_preview"
            ],
            "description": "Entity name."
          },
          "product_key": {
            "type": "string",
            "example": "annual_state_filing"
          },
          "display_name": {
            "type": "string"
          },
          "unit_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Your price for this product and profile, in cents - your override or a matching price rule when one applies, otherwise the default."
          },
          "currency": {
            "type": "string",
            "example": "usd"
          },
          "interval": {
            "type": "string",
            "enum": [
              "one_time",
              "monthly",
              "yearly"
            ]
          },
          "overridden": {
            "type": "boolean",
            "description": "True when your negotiated sheet priced this product."
          },
          "applied_rule": {
            "type": "string",
            "description": "The price rule that decided `unit_amount` for this profile, when one matched - why this profile pays this amount."
          },
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductOption"
            },
            "description": "The product's variants with each value's own effective amount - a chosen value's amount replaces `unit_amount`."
          },
          "fees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PricePreviewFee"
            },
            "description": "The pass-through government and state fee lines an order would bill beside the product, at today's amounts. A fee the state does not charge (or whose price is not configured yet) produces no line."
          },
          "estimate": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Always true - amounts here are resolved now. The order's own resolution governs and is frozen on the order."
          }
        }
      },
      "CompanyPricePreviewBody": {
        "type": "object",
        "description": "The price-relevant slice of a company create - enough to resolve the whole basket.",
        "required": [
          "entity_type",
          "state"
        ],
        "properties": {
          "entity_type": {
            "type": "string",
            "enum": [
              "llc",
              "c_corp"
            ]
          },
          "state": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$",
            "description": "The formation state, as a 2-letter code.",
            "example": "DE"
          },
          "pre_existing": {
            "type": "boolean",
            "description": "Preview for a pre-existing company you bring in (no formation line). Defaults to false."
          },
          "has_ein": {
            "type": "boolean",
            "description": "Whether the pre-existing company you bring in already holds an EIN. Only a pre_existing company can (a formation is assigned one later), so it is ignored otherwise. It changes which services are available - an EIN service is for companies without one. Defaults to false."
          },
          "owners_count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "How many owners the company has. Defaults to 1."
          },
          "services": {
            "type": "array",
            "description": "Service product keys to attach. Mandatory services are added automatically whether or not they are listed.",
            "items": {
              "type": "string"
            }
          },
          "formation_options": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Option choices for the formation itself, e.g. `{\"turnaround\":\"expedited\"}`. This is a shorthand for `service_options` under the `formation` key. Prefer putting the formation's options in `service_options`, which is the field the create request reads, so the same input drives both this quote and the charge. When both are given, `service_options.formation` takes precedence."
          },
          "service_options": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "description": "Per-service option choices, keyed by product key, e.g. `{\"ein\":{\"turnaround\":\"expedited\"}}`. The formation's own options belong here too, under the `formation` key, in the same shape the create request reads, so the quote and the charge use the same option amounts."
          }
        }
      },
      "CompanyBasketLine": {
        "type": "object",
        "description": "One prospective charge of a company create - the formation or a service, with its own amount, interval and any pass-through fees.",
        "required": [
          "kind",
          "product_key",
          "unit_amount",
          "currency"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "formation",
              "service"
            ],
            "description": "Whether this line is the formation itself or a service on it."
          },
          "product_key": {
            "type": "string",
            "example": "registered_agent"
          },
          "unit_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Your partner price in cents (the override, a matching rule, or the default), or the chosen option's amount when one is picked."
          },
          "currency": {
            "type": "string",
            "example": "usd"
          },
          "interval": {
            "type": "string",
            "description": "How this line bills - one_time, monthly or yearly.",
            "example": "one_time"
          },
          "required": {
            "type": "boolean",
            "description": "True when the profile auto-attaches this service (mandatory), rather than the caller listing it."
          },
          "applied_rule": {
            "type": "string",
            "description": "The price rule that decided the amount, absent when the default or an override priced it."
          },
          "fees": {
            "type": "array",
            "description": "Pass-through government or state fee lines for this product, at today's amounts.",
            "items": {
              "$ref": "#/components/schemas/PricePreviewFee"
            }
          }
        }
      },
      "CompanyPricePreview": {
        "type": "object",
        "description": "Every line a company create would bill for a stated profile, before anything exists: the formation with its state filing fee, every mandatory service the profile auto-attaches, and every service listed. Each line carries its own interval - they are not summed, since a one-time formation and a yearly service are not one number. Amounts are estimates: the create resolves again and freezes what it billed.",
        "required": [
          "object",
          "currency",
          "lines"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "company_price_preview"
            ],
            "description": "Entity name."
          },
          "currency": {
            "type": "string",
            "example": "usd"
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompanyBasketLine"
            }
          }
        }
      },
      "StatusToken": {
        "type": "object",
        "description": "A read-only status link you hand to an end customer.",
        "required": [
          "object",
          "id",
          "created_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "status_token"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "pattern": "^stok_[0-9A-Za-z]{22}$",
            "description": "The token's management id - revoke by this."
          },
          "url": {
            "type": "string",
            "description": "The keyless status link, shown once at creation and never returned again."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "StatusTokenList": {
        "type": "object",
        "description": "A company's status links. Unpaginated - the set is small.",
        "required": [
          "object",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ],
            "description": "Entity name."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StatusToken"
            }
          }
        }
      },
      "StatusService": {
        "type": "object",
        "description": "One service on the status view - no price, no personal data.",
        "required": [
          "object",
          "product_key",
          "status"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "status_service"
            ],
            "description": "Entity name."
          },
          "product_key": {
            "type": "string",
            "example": "ein"
          },
          "status": {
            "type": "string",
            "example": "in_progress"
          }
        }
      },
      "StatusView": {
        "type": "object",
        "description": "A company's live status as an end customer sees it: where the formation and services stand, and nothing else. No documents, no personal data, no prices.",
        "required": [
          "object",
          "company_name",
          "state",
          "entity_type",
          "status",
          "verification",
          "services",
          "updated_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "status"
            ],
            "description": "Entity name."
          },
          "company_name": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Formation status."
          },
          "verification": {
            "type": "string",
            "description": "Verification state."
          },
          "services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StatusService"
            }
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Invoice": {
        "type": "object",
        "description": "An invoice raised on your account at month end.",
        "required": [
          "object",
          "id",
          "amount_due",
          "amount_paid",
          "currency",
          "status",
          "created_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "invoice"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "description": "The invoice identifier.",
            "example": "in_1QabcXYZ"
          },
          "number": {
            "type": "string",
            "description": "The human-facing invoice number, once assigned."
          },
          "amount_due": {
            "type": "integer",
            "format": "int64",
            "description": "Amount due in the currency's smallest unit (cents).",
            "example": 43600
          },
          "amount_paid": {
            "type": "integer",
            "format": "int64",
            "description": "Amount paid so far, in cents."
          },
          "currency": {
            "type": "string",
            "example": "usd"
          },
          "status": {
            "type": "string",
            "description": "Invoice status: open, paid, uncollectible, or void.",
            "example": "open"
          },
          "hosted_url": {
            "type": "string",
            "description": "A short-lived link to the hosted invoice, when available."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TaxFilingCorpInfo": {
        "type": "object",
        "additionalProperties": false,
        "description": "The filing's corporate identity. Prefilled from the company when the filing is created - send only what differs.",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "Legal company name as it should appear on the return."
          },
          "state": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "Two-letter formation state code."
          },
          "entity_type": {
            "type": "string",
            "enum": [
              "llc",
              "c_corp"
            ]
          },
          "industry": {
            "type": "string",
            "maxLength": 255
          },
          "parent_company": {
            "type": "string",
            "maxLength": 255,
            "description": "The parent company's name, when one exists."
          },
          "ein": {
            "type": "string",
            "maxLength": 20,
            "description": "Employer Identification Number, 12-3456789."
          },
          "formation_date": {
            "type": "string",
            "maxLength": 20,
            "description": "Formation date as shown on the formation documents."
          },
          "initial_return": {
            "type": "boolean",
            "description": "True when this is the company's first return."
          },
          "issued_shares": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "gross_assets": {
            "type": "number",
            "minimum": 0
          },
          "dba": {
            "type": "string",
            "maxLength": 255,
            "description": "Doing-business-as name, when one exists."
          },
          "principal_business_activity": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "TaxFilingContact": {
        "type": "object",
        "additionalProperties": false,
        "description": "Who Clemta reaches with questions about the return.",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "phone": {
            "type": "string",
            "minLength": 7,
            "maxLength": 20,
            "pattern": "^[0-9+()\\s.-]+$",
            "description": "Digits with optional `+`, spaces, and `()`.-` separators - the same shape phone takes everywhere on this API."
          },
          "phone_country": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$",
            "description": "The phone's ISO 3166 alpha-2 country code, e.g. `us`."
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 255,
            "description": "Required before the filing can be submitted."
          },
          "principal_place_of_business": {
            "$ref": "#/components/schemas/Address",
            "description": "Where the company is actually administered from. A registered agent address is not accepted here by the state."
          }
        }
      },
      "TaxFilingQuestions": {
        "type": "object",
        "additionalProperties": false,
        "description": "The return's yes/no questions. An omitted answer reads as not answered.",
        "properties": {
          "has_employees": {
            "type": "boolean"
          },
          "made_1099_payments": {
            "type": "boolean",
            "description": "Payments were made that require filing form 1099. When true, the filing cannot be submitted until at least one IRS-1099 file is attached via `form_1099_files`."
          },
          "form_1099_files": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "string",
              "pattern": "^file_[0-9A-Za-z]{22}$"
            },
            "description": "IRS-1099 files to attach, by file id - upload each via `POST /v1/files` with purpose `tax_form_1099`, then reference the ids here. Write-only and single-use: attached files land with Clemta and the read answers their count as `form_1099_count` on the filing."
          },
          "purchased_assets": {
            "type": "boolean",
            "description": "Assets were purchased during the filing year."
          },
          "owns_non_us_corp": {
            "type": "boolean",
            "description": "The company owns a non-US corporation."
          },
          "has_us_physical_presence": {
            "type": "boolean"
          }
        }
      },
      "TaxFilingOwner": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name"
        ],
        "description": "One owner line on the return - a person or an entity holding equity. The four tax ids are parallel fields, as the return asks them: `ftin` and `itin` are expected for every owner (write \"0\" where one does not exist), `ssn` belongs to individuals, `ein` to organizations.",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255
          },
          "title": {
            "type": "string",
            "maxLength": 120
          },
          "type": {
            "type": "string",
            "maxLength": 60,
            "description": "Free-form kind, e.g. Individual or Organization."
          },
          "ftin": {
            "type": "string",
            "maxLength": 40,
            "description": "Foreign tax identification number issued by the owner's home country. Expected for every owner - write \"0\" when the owner has none."
          },
          "itin": {
            "type": "string",
            "maxLength": 20,
            "description": "IRS individual taxpayer identification number. Expected for every owner - write \"0\" when the owner has none."
          },
          "ssn": {
            "type": "string",
            "pattern": "^\\d{3}-\\d{2}-\\d{4}$",
            "description": "US Social Security Number, individuals only, when available."
          },
          "ein": {
            "type": "string",
            "pattern": "^\\d{2}-\\d{7}$",
            "description": "Employer Identification Number, organization owners only, when available."
          },
          "phone": {
            "type": "string",
            "maxLength": 32
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "capital_contributions": {
            "type": "number",
            "minimum": 0
          },
          "percentage_owned": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "TaxFilingSales": {
        "type": "object",
        "additionalProperties": false,
        "description": "The sales block of the revenue and expenses section.",
        "properties": {
          "gross_sales": {
            "type": "number",
            "minimum": 0
          },
          "returns_and_allowances": {
            "type": "number",
            "minimum": 0
          },
          "sales": {
            "type": "number",
            "minimum": 0
          }
        }
      },
      "TaxFilingCogs": {
        "type": "object",
        "additionalProperties": false,
        "description": "The cost-of-goods-sold block of the revenue and expenses section.",
        "properties": {
          "beginning_inventory": {
            "type": "number",
            "minimum": 0
          },
          "purchases": {
            "type": "number",
            "minimum": 0
          },
          "ending_inventory": {
            "type": "number",
            "minimum": 0
          }
        }
      },
      "TaxFilingRevenueExpenses": {
        "type": "object",
        "additionalProperties": false,
        "description": "The federal filing's numbers - sales, cost of goods sold, and expenses by category. Required before a federal filing can be submitted.",
        "properties": {
          "sales": {
            "$ref": "#/components/schemas/TaxFilingSales"
          },
          "cost_of_goods_sold": {
            "$ref": "#/components/schemas/TaxFilingCogs"
          },
          "expenses": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Expense amounts keyed by category. Accepted keys - accounting, advertising, bad_debts, bank_charge, cell_phone, commission, consulting, delivery, dues_and_subscriptions, education_and_training, employee_benefit, entertainment, fuel, guaranteed_payment, insurance, general, building_and_equipment, liability, workers_compensation, other_insurance, internet_service, janitorial, legal, marketing, office_expense, parking_tolls, payroll, payroll_processing_service, permit_and_fees, postage_shipping, printing, recruiting, rent, repair_and_maintenance, software, taxes_and_licenses, telephone, travel, utilities, waste_removal, other. An unknown key is refused with a suggestion."
          },
          "principal_business_activity": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "TaxFilingBalanceSheet": {
        "type": "object",
        "additionalProperties": false,
        "description": "The state filing's balance sheet. Required before a state filing can be submitted.",
        "properties": {
          "lines": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Balance sheet amounts keyed by line. Accepted keys - cash, trade_notes_and_accounts_receivable, subtract_allowance_for_bad_debts, inventories, government_obligations, tax_exempt_securities, other_current_assets, loan_to_shareholders, mortgage_and_real_estate_loans, other_investments, buildings_and_other_depreciable, depletable_assets, land, intangible_assets, subtract_accumulated_amortization, other_assets. An unknown key is refused with a suggestion."
          },
          "principal_business_activity": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "TaxFilingFixedAsset": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "title"
        ],
        "description": "One depreciable asset line on the filing. Read-only and register-derived - manage assets with the fixed-assets API. Same shape as the FixedAsset resource.",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 255
          },
          "placed_in_service": {
            "type": "string",
            "format": "date",
            "description": "The date the asset was placed in service (YYYY-MM-DD)."
          },
          "cost": {
            "type": "number",
            "format": "double",
            "minimum": 0
          },
          "salvage_value": {
            "type": "number",
            "format": "double",
            "minimum": 0
          },
          "business_use": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "maximum": 100,
            "description": "Business-use percentage."
          }
        }
      },
      "TaxFilingPerson": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "first_name",
          "last_name"
        ],
        "description": "An officer or director line on the return.",
        "properties": {
          "first_name": {
            "type": "string",
            "maxLength": 120
          },
          "last_name": {
            "type": "string",
            "maxLength": 120
          },
          "title": {
            "type": "string",
            "maxLength": 120
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "TaxFilingForm": {
        "type": "object",
        "additionalProperties": false,
        "description": "The filing questionnaire. Every section is optional on a write - a section you send replaces the stored one whole, a section you omit stays as it is. Federal filings use `revenue_expenses`, state filings use `balance_sheet`.",
        "properties": {
          "corp_info": {
            "$ref": "#/components/schemas/TaxFilingCorpInfo"
          },
          "contact": {
            "$ref": "#/components/schemas/TaxFilingContact"
          },
          "additional_questions": {
            "$ref": "#/components/schemas/TaxFilingQuestions"
          },
          "owners": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/TaxFilingOwner"
            },
            "description": "The equity holders as they should appear on the return."
          },
          "revenue_expenses": {
            "$ref": "#/components/schemas/TaxFilingRevenueExpenses"
          },
          "balance_sheet": {
            "$ref": "#/components/schemas/TaxFilingBalanceSheet"
          },
          "fixed_assets": {
            "type": "array",
            "maxItems": 200,
            "readOnly": true,
            "description": "Read-only. The company's fixed assets are drawn from its register at save time - manage them with the fixed-assets API (`/v1/companies/{id}/fixed-assets`), not here. Any value sent in this field is ignored.",
            "items": {
              "$ref": "#/components/schemas/TaxFilingFixedAsset"
            }
          },
          "officers": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/TaxFilingPerson"
            }
          },
          "directors": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/TaxFilingPerson"
            }
          }
        }
      },
      "TaxFilingGap": {
        "type": "object",
        "required": [
          "field",
          "reason"
        ],
        "additionalProperties": false,
        "description": "One unmet requirement keeping the filing from being submitted.",
        "properties": {
          "field": {
            "type": "string",
            "description": "Dotted path of the missing field or section, e.g. `contact.email`.",
            "example": "contact.email"
          },
          "reason": {
            "type": "string",
            "enum": [
              "required",
              "required_for_federal",
              "required_for_state",
              "required_when_1099",
              "unsupported_state"
            ],
            "description": "Why the field is needed. `required` is always needed, `required_for_federal` and `required_for_state` are needed for that filing type, `required_when_1099` is needed once the filing reports 1099 payments, and `unsupported_state` means the company's state is not filable."
          }
        }
      },
      "TaxFiling": {
        "type": "object",
        "description": "One federal or state tax filing on a company. Open it over the API, fill the form, and submit it - or your customer can open and fill it themselves. The filing entitlement is spent at submit. Follow progress with `tax_filing.created` / `tax_filing.status.changed`.",
        "required": [
          "object",
          "id",
          "company",
          "year",
          "type",
          "status",
          "livemode",
          "created_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "tax_filing"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "pattern": "^txf_[0-9A-Za-z]{22}$",
            "example": "txf_0346sFPEvSkJvY8vt14NNw"
          },
          "company": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$"
          },
          "year": {
            "type": "integer",
            "format": "int64",
            "description": "The filing year.",
            "example": 2025
          },
          "type": {
            "type": "string",
            "enum": [
              "federal",
              "state"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "in_review",
              "accepted",
              "rejected"
            ],
            "description": "Review outcome: `draft` while the customer fills it in, `in_review` once submitted to Clemta, then `accepted` or `rejected`. A `rejected` filing is re-openable - it can be corrected and resubmitted, moving it back to `in_review`."
          },
          "progress": {
            "type": "string",
            "enum": [
              "draft",
              "in_progress",
              "additional_info",
              "signature_requested",
              "return_ready",
              "completed"
            ],
            "description": "Where Clemta has the return. `additional_info` and `signature_requested` need the customer. `return_ready` means the return is available in the company's documents. `completed` is filed."
          },
          "form": {
            "$ref": "#/components/schemas/TaxFilingForm",
            "description": "The questionnaire as currently stored. Present on the detail read and on write answers, absent on the list."
          },
          "form_1099_count": {
            "type": "integer",
            "description": "How many IRS-1099 files are attached to the filing, however they were attached them. Present on the detail read and on write answers."
          },
          "submittable": {
            "type": "boolean",
            "description": "True when the filing is editable (a draft, or a rejected filing sent back for correction) with every required section in place. Present on the detail read and on write answers."
          },
          "missing": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxFilingGap"
            },
            "description": "What still keeps the filing from being submitted, field by field. Empty when `submittable` is true. Present on the detail read and on write answers."
          },
          "livemode": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CalendarEventVariables": {
        "type": "object",
        "description": "Whitelabel-safe facts about this deadline and its company, ready to drop into your own reminder over any channel - email, SMS, a chat message. These are the same neutral values the platform fills its own reminder mail template with. The platform's branded copy, links and sender are never exposed, so you word and send the message yourself.",
        "properties": {
          "company_name": {
            "type": "string",
            "example": "Hall Young"
          },
          "company_ending": {
            "type": "string",
            "example": "L.L.C."
          },
          "company_state": {
            "type": "string",
            "description": "The full state name the company was formed in.",
            "example": "Wyoming"
          },
          "company_type": {
            "type": "string",
            "enum": [
              "llc",
              "c_corp"
            ]
          },
          "formation_month": {
            "type": "string",
            "description": "The month the company was formed, as an English month name. Empty until the company is incorporated.",
            "example": "September"
          },
          "days_remaining": {
            "type": "integer",
            "description": "Whole days from now until due_at at the moment this was produced, negative once the deadline has passed. On a `calendar.reminder` webhook it is the count at the reminder point that fired.",
            "example": 41
          }
        }
      },
      "CalendarEvent": {
        "type": "object",
        "description": "One compliance calendar item on a company - an annual report deadline, a franchise tax date. Read them from the calendar endpoint, and receive a `calendar.reminder` webhook ahead of each one. No mail is sent to your customer. The notification channel is yours.",
        "required": [
          "object",
          "id",
          "company",
          "title",
          "due_at",
          "livemode"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "calendar_event"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "pattern": "^cal_[0-9A-Za-z]{22}$",
            "example": "cal_0346sFPEvSkJvY8vt14NNw",
            "description": "The calendar entry's identifier, stable across reads."
          },
          "company": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$",
            "description": "The company the deadline is on."
          },
          "title": {
            "type": "string",
            "example": "Annual Report Filing"
          },
          "category": {
            "type": "string",
            "enum": [
              "registered_agent_renewal",
              "state_annual_compliance",
              "annual_report",
              "estimated_tax_q1",
              "estimated_tax_q2",
              "estimated_tax_q3",
              "estimated_tax_q4",
              "client_event",
              "other"
            ],
            "description": "What kind of deadline this is, as a stable token - so you can group, icon and word your own reminder without parsing the free-text title. `client_event` is one your customer added. `other` is a deadline whose kind is not yet classified."
          },
          "description": {
            "type": "string",
            "description": "Present only on a customer-added event. Standard compliance deadlines carry no description - use `category` to word your own. The platform's own copy is never exposed."
          },
          "due_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the item is due."
          },
          "end_at": {
            "type": "string",
            "format": "date-time",
            "description": "The end of the window, when the item spans one."
          },
          "all_day": {
            "type": "boolean",
            "description": "True when the item is a date rather than a moment."
          },
          "remind_at": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Every reminder point for this deadline, soonest first. Present on both calendar reads and `calendar.reminder` webhooks - so you can render an upcoming-reminders view from the read alone. On a webhook, the envelope `timestamp` is the reminder point that fired."
          },
          "variables": {
            "$ref": "#/components/schemas/CalendarEventVariables"
          },
          "livemode": {
            "type": "boolean"
          }
        }
      },
      "EventData": {
        "type": "object",
        "required": [
          "object"
        ],
        "additionalProperties": false,
        "description": "The event's payload: the resource the event is about, embedded as of when the event occurred. This is a point-in-time snapshot, not a live read - a delivery that arrives late still carries the state that triggered it.",
        "properties": {
          "object": {
            "description": "The resource this event concerns, tagged by its own `object` field. A company today. More resource types are added over time, so switch on `object` rather than assuming a shape.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/Company"
              },
              {
                "$ref": "#/components/schemas/ServiceOrder"
              },
              {
                "$ref": "#/components/schemas/Invoice"
              },
              {
                "$ref": "#/components/schemas/Requirement"
              },
              {
                "$ref": "#/components/schemas/File"
              },
              {
                "$ref": "#/components/schemas/TaxFiling"
              },
              {
                "$ref": "#/components/schemas/CalendarEvent"
              }
            ],
            "discriminator": {
              "propertyName": "object",
              "mapping": {
                "company": "#/components/schemas/Company",
                "service_order": "#/components/schemas/ServiceOrder",
                "invoice": "#/components/schemas/Invoice",
                "requirement": "#/components/schemas/Requirement",
                "file": "#/components/schemas/File",
                "tax_filing": "#/components/schemas/TaxFiling",
                "calendar_event": "#/components/schemas/CalendarEvent"
              }
            }
          }
        }
      },
      "Event": {
        "type": "object",
        "required": [
          "object",
          "id",
          "type",
          "data",
          "livemode",
          "created_at",
          "timestamp"
        ],
        "additionalProperties": false,
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "event"
            ],
            "description": "Entity name. Identifies this object when it arrives without its URL."
          },
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9A-Za-z]{22}$",
            "description": "Identifier of the event.",
            "example": "evt_0346sFPEvSkJvY8vt14NNw"
          },
          "type": {
            "type": "string",
            "description": "What happened, e.g. `company.created`, `company.status.changed`, `company.verified`. Branch on this. New types may be added over time, so treat an unrecognized one as informational rather than an error."
          },
          "company_id": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$",
            "description": "The company the event is about, when it is about one."
          },
          "company": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Company"
              }
            ],
            "description": "The full company this event is about. Present only when requested with `expand[]=company`, and only for an event that carries a `company_id`."
          },
          "data": {
            "$ref": "#/components/schemas/EventData"
          },
          "livemode": {
            "type": "boolean",
            "description": "False for an event recorded in a test-key stream."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When the fact the event describes occurred, ISO 8601 - the Standard Webhooks envelope field. Usually identical to `created_at`, because events are recorded in the same transaction as their change. Where a truer stamp exists it is used instead and can PRECEDE `created_at`: `company.incorporated` carries the incorporation stamp itself, which can predate when the event was recorded, and `calendar.reminder` carries the remind moment. Filter and page by `created_at` (the record clock). Read `timestamp` for when it happened. The time of a delivery ATTEMPT is a third thing and never appears in the payload - it is the `webhook-timestamp` header, fresh on every retry."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the event was recorded."
          }
        }
      },
      "EventList": {
        "type": "object",
        "required": [
          "object",
          "page",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ],
            "description": "Entity name."
          },
          "page": {
            "$ref": "#/components/schemas/Page"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          }
        }
      },
      "SandboxTaxFiling": {
        "type": "object",
        "description": "The tax filing to open or move (sandbox).",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "federal",
              "state"
            ]
          },
          "year": {
            "type": "integer",
            "format": "int64",
            "description": "Filing year. Defaults to the current year."
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "in_review",
              "accepted",
              "rejected"
            ],
            "default": "draft"
          },
          "progress": {
            "type": "string",
            "enum": [
              "draft",
              "in_progress",
              "additional_info",
              "signature_requested",
              "return_ready",
              "completed"
            ],
            "default": "draft"
          }
        }
      },
      "SandboxSigner": {
        "type": "object",
        "required": [
          "email"
        ],
        "additionalProperties": false,
        "description": "One signer on a simulated signature requirement. A test signature has no real provider round, so a signer is just an email and a display name - no owner check, no disposable-domain screen.",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "The signer's email. Each signer on the document needs a distinct one."
          },
          "name": {
            "type": "string",
            "maxLength": 200,
            "description": "The signer's display name, shown on the hosted signing page."
          },
          "role": {
            "type": "string",
            "maxLength": 100,
            "description": "Optional label for the party this signer fills on the document. Omitted with a `person_ref`, it is derived from that person - a shareholder's title, an officer's role."
          },
          "person_ref": {
            "type": "string",
            "description": "Optional. A shareholder or officer id (`sh_`/`off_`) of the company this signer IS, when picked from the company's people rather than typed by hand. The requirement's signer then carries `person`, and it must name a real person on the company."
          }
        }
      },
      "SandboxSimulateBody": {
        "type": "object",
        "required": [
          "event"
        ],
        "additionalProperties": false,
        "description": "Which event to simulate on a test company. The company (or its order, filing, file) is moved exactly as a live change would move it, then the event is delivered to your test webhooks - so every handler can be rehearsed against the real behaviour. Only the fields the event uses are read.",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "company.status.changed",
              "company.incorporated",
              "company.verified",
              "company.name.changed",
              "company.ein.assigned",
              "company.entitlements.changed",
              "service_order.status.changed",
              "service_order.completed",
              "service_order.quoted",
              "service_order.renewal_canceled",
              "service_order.renewal_cancel_denied",
              "service_order.updated",
              "tax_filing.created",
              "tax_filing.status.changed",
              "file.created",
              "requirement.created",
              "invoice.finalized"
            ],
            "description": "The event to produce. Events with a once-only rule keep it here too: `company.incorporated` fires the first time only. A bounce through `company.status.changed` back to `active` fires `status.changed` and not `incorporated` again."
          },
          "status": {
            "type": "string",
            "enum": [
              "in_progress",
              "active",
              "cancelled"
            ],
            "description": "For `company.status.changed` - the status to move to. Moving to `active` the first time also fires `company.incorporated`."
          },
          "name": {
            "type": "string",
            "maxLength": 200,
            "description": "For `company.name.changed` - the new legal name."
          },
          "ein": {
            "type": "string",
            "pattern": "^[0-9]{2}-[0-9]{7}$",
            "description": "For `company.ein.assigned`. A second, different EIN updates the field without firing again."
          },
          "entitlements": {
            "$ref": "#/components/schemas/CompanyEntitlements"
          },
          "order": {
            "type": "string",
            "pattern": "^so_[0-9A-Za-z]{22}$",
            "description": "For `service_order.*` - the test order on this company."
          },
          "step": {
            "type": "string",
            "maxLength": 100,
            "description": "For `service_order.status.changed` - the workflow step name to move the order to."
          },
          "form_required": {
            "type": "boolean",
            "description": "For `service_order.status.changed` - whether the step waits on a form (opens a `form` requirement, status `requires_action`). The requirement's `form.fields` are the product's real form for that step - the same schema the order would show live."
          },
          "completed": {
            "type": "boolean",
            "description": "For `service_order.status.changed` - whether the step is the final one (status `completed`, fires `service_order.completed`)."
          },
          "amount": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "description": "For `service_order.quoted` - the quoted amount in minor units, on a quote-priced test order (one created for a `get_a_quote` product). After it, the order can be accepted with `POST /companies/{id}/service-orders/{orderID}/accept-quote`."
          },
          "currency": {
            "type": "string",
            "maxLength": 3,
            "description": "For `service_order.quoted` - the quote's ISO currency. Defaults to the order's, else `usd`."
          },
          "outcome": {
            "type": "string",
            "maxLength": 100,
            "description": "For `service_order.updated` - the outcome recorded on a completed test order (e.g. a bank application `approved`/`declined`, a certificate `not_eligible`). The order must already be completed."
          },
          "tax_filing": {
            "$ref": "#/components/schemas/SandboxTaxFiling"
          },
          "file_name": {
            "type": "string",
            "maxLength": 200,
            "description": "For `file.created` - the document's filename. A placeholder PDF is served from the file's content endpoint."
          },
          "message": {
            "type": "string",
            "maxLength": 500,
            "description": "For `requirement.created` - the ask's note to the client (an `information` requirement, or the signature's message)."
          },
          "requirement_type": {
            "type": "string",
            "enum": [
              "information",
              "signature"
            ],
            "description": "For `requirement.created` - which kind of requirement to open. Defaults to `information`. `signature` opens a signature ask for `signers` (the partner then mints a signing session and completes it in test mode)."
          },
          "signers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SandboxSigner"
            },
            "minItems": 1,
            "maxItems": 20,
            "description": "For `requirement.created` with `requirement_type: signature` - the signers the signature ask is opened for. At least one is required."
          },
          "document_name": {
            "type": "string",
            "maxLength": 200,
            "description": "For `requirement.created` with `requirement_type: signature` - the document's display name."
          },
          "sequential": {
            "type": "boolean",
            "description": "For `requirement.created` with `requirement_type: signature` - make the signers sign in roster order (each waits for the one before). Off by default (everyone can sign in parallel)."
          }
        }
      },
      "Clock": {
        "type": "object",
        "required": [
          "object",
          "id",
          "livemode",
          "simulated_time",
          "created_at"
        ],
        "additionalProperties": false,
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "clock"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "example": "clk_0346sFPEvSkJvY8vt14NNw"
          },
          "livemode": {
            "type": "boolean",
            "description": "The mode this clock simulates. A test clock is always available. On the production API a live clock is refused - it is a sandbox rehearsal tool."
          },
          "simulated_time": {
            "type": "string",
            "format": "date-time",
            "description": "The moment your simulated world has reached. It starts at the real current time when the clock is created and only ever moves forward. Advancing it processes every renewal and billing event that comes due up to this moment."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "advanced_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the clock was last advanced. Absent until the first advance."
          }
        }
      },
      "AdvanceClockBody": {
        "type": "object",
        "required": [
          "to"
        ],
        "additionalProperties": false,
        "properties": {
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "The moment to advance the simulated world to. Must be after the clock's current simulated_time, at most five years ahead of it per call. Every renewal period due before this moment bills on your ledger during the call, and on a live clock each month boundary crossed drafts that month's statement.",
            "example": "2027-09-08T00:00:00Z"
          }
        }
      },
      "PagedFileList": {
        "type": "object",
        "required": [
          "object",
          "page",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "page": {
            "$ref": "#/components/schemas/Page"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/File"
            }
          }
        }
      },
      "FileList": {
        "type": "object",
        "description": "A company's published documents, newest first.",
        "required": [
          "object",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/File"
            }
          }
        }
      },
      "TaxFilingList": {
        "type": "object",
        "required": [
          "object",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxFiling"
            }
          }
        }
      },
      "CreateTaxFilingBody": {
        "type": "object",
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "description": "Opens a filing for the current year. The slot is one filing per company, type and year. Creating is free - the filing entitlement is spent at submit, not here - so an abandoned draft never costs a right.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "federal",
              "state"
            ]
          },
          "form": {
            "$ref": "#/components/schemas/TaxFilingForm",
            "description": "Sections to fill at creation. Identity fields prefill from the company - send only what differs."
          },
          "submit": {
            "type": "boolean",
            "description": "True runs create, fill and submit as one atomic call - the filing lands with Clemta immediately, or nothing is created at all. Requires a complete form and an available filing entitlement."
          }
        }
      },
      "UpdateTaxFilingBody": {
        "type": "object",
        "required": [
          "form"
        ],
        "additionalProperties": false,
        "description": "Replaces the provided form sections on an editable filing. A filing is editable while it is a draft, and again if it was rejected - a rejected filing can be corrected and resubmitted. Once it is in review or accepted it is closed, and changes go through Clemta.",
        "properties": {
          "form": {
            "$ref": "#/components/schemas/TaxFilingForm"
          }
        }
      },
      "CalendarEventList": {
        "type": "object",
        "description": "A company's compliance calendar, soonest first. Unpaginated - the set is small and bounded.",
        "required": [
          "object",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CalendarEvent"
            }
          }
        }
      },
      "CreateCalendarEventBody": {
        "type": "object",
        "description": "A calendar event to add to a company, beside the compliance deadlines. Your own event - a filing you track, a customer meeting, an internal deadline - in a clean, self-contained shape. You choose how many days before to be reminded. A `calendar.reminder` webhook fires at each point so you notify your customer on your own channel.",
        "required": [
          "title",
          "due_at"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "example": "Beneficial ownership update"
          },
          "description": {
            "type": "string",
            "maxLength": 2000,
            "description": "Your own note for the event. Shown back on reads and reminder webhooks - the platform never adds copy of its own."
          },
          "due_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the event is due."
          },
          "end_at": {
            "type": "string",
            "format": "date-time",
            "description": "The end of the window, when the event spans one. Must not be before due_at."
          },
          "all_day": {
            "type": "boolean",
            "description": "True when the event is a date rather than a moment."
          },
          "remind_before_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 365
            },
            "description": "Days before due_at to be reminded, each firing one `calendar.reminder` webhook. Exposed back as absolute remind_at moments. Omit for an event with no reminders."
          }
        }
      },
      "FileLink": {
        "type": "object",
        "description": "A file link shares one file's contents with someone who holds no API key: the `url` serves the bytes without authentication until the link expires. Create one to hand a deliverable to your customer or a downstream system. Only shareable files can be linked - an identity document can never be turned into a URL.",
        "required": [
          "object",
          "id",
          "file",
          "url",
          "expired",
          "livemode",
          "created_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "file_link"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "pattern": "^link_[0-9A-Za-z]{22}$",
            "example": "link_0346sFPEvSkJvY8vt14NNw"
          },
          "file": {
            "type": "string",
            "pattern": "^file_[0-9A-Za-z]{22}$",
            "description": "The file this link serves."
          },
          "url": {
            "type": "string",
            "description": "The public contents URL. The URL is the credential - anyone holding it can read the file until the link expires - so treat it like a secret."
          },
          "expired": {
            "type": "boolean",
            "description": "Whether the link has expired. Expired links answer 404."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the link stops serving. Absent means it never expires."
          },
          "livemode": {
            "type": "boolean"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Your own key-value notes on the link, stored and returned verbatim."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PagedFileLinkList": {
        "type": "object",
        "required": [
          "object",
          "page",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "page": {
            "$ref": "#/components/schemas/Page"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileLink"
            }
          }
        }
      },
      "CreateFileLinkBody": {
        "type": "object",
        "required": [
          "file"
        ],
        "additionalProperties": false,
        "properties": {
          "file": {
            "type": "string",
            "pattern": "^file_[0-9A-Za-z]{22}$",
            "description": "The file to share."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the link stops serving. Omit for a link that never expires."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "UpdateFileLinkBody": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "expires_at": {
            "type": "string",
            "maxLength": 40,
            "description": "An RFC3339 timestamp to move the expiry, or the literal `now` to expire the link immediately - the way to revoke a URL that is already in someone's hands."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Replaces the stored metadata when present."
          }
        }
      },
      "RequirementList": {
        "type": "object",
        "description": "Your requirements, newest first.",
        "required": [
          "object",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Requirement"
            }
          }
        }
      },
      "FulfillRequirementBody": {
        "type": "object",
        "description": "What fulfills the requirement: answers for a `form`, `name_change` or `information` requirement, a file for a `document` one. Files are uploaded first (POST /v1/files, with the purpose the requirement names) and attached here by id.",
        "properties": {
          "document": {
            "type": "string",
            "pattern": "^file_[0-9A-Za-z]{22}$",
            "description": "For a `document` requirement: the uploaded file that fulfills it, by id. Single-use."
          },
          "documents": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "type": "string",
              "pattern": "^file_[0-9A-Za-z]{22}$"
            },
            "description": "For a `document` requirement with several pages (a passport's front and back): uploaded files, first one primary. Bounded by the purpose's policy (max_files)."
          },
          "values": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ServiceFormField"
            },
            "description": "The answers. A `name_change` expects one value with key `name`. A `form` takes the keys from the requirement's `form` schema."
          }
        }
      },
      "CreateVerificationSessionBody": {
        "type": "object",
        "required": [
          "shareholder"
        ],
        "additionalProperties": false,
        "properties": {
          "shareholder": {
            "type": "string",
            "pattern": "^sh_[0-9A-Za-z]{22}$",
            "description": "The owner whose identity document is being collected."
          },
          "embed_origin": {
            "type": "string",
            "maxLength": 255,
            "description": "Frame this session inside your own site: the exact https origin (for example `https://app.yourbrand.com`) the page will be embedded on. The origin must first be registered under your hosted page's `embed_origins`. Omit it for an ordinary full-page session - the page then refuses to be framed anywhere."
          }
        }
      },
      "VerificationSession": {
        "type": "object",
        "description": "A short-lived hosted-upload session for one owner's identity document. Create one when you need a URL to hand (or redirect) your customer to. The page carries your brand and your legal links from the verification page configuration. Sessions are repeatable - mint another when one expires.",
        "required": [
          "object",
          "company",
          "shareholder",
          "url",
          "expires_at",
          "livemode"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "verification_session"
            ]
          },
          "company": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$"
          },
          "shareholder": {
            "type": "string",
            "pattern": "^sh_[0-9A-Za-z]{22}$"
          },
          "url": {
            "type": "string",
            "description": "Where to send your customer. The URL is the credential - it authorizes exactly this owner's document upload, nothing else - so treat it like a secret and pass it over a secure channel."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "livemode": {
            "type": "boolean"
          }
        }
      },
      "CreateSigningSessionBody": {
        "type": "object",
        "required": [
          "requirement"
        ],
        "additionalProperties": false,
        "properties": {
          "requirement": {
            "type": "string",
            "pattern": "^rqmt_[0-9A-Za-z]{22}$",
            "description": "The open signature requirement to mint a session for."
          },
          "signer": {
            "type": "string",
            "maxLength": 254,
            "description": "Which signer this session is for, by email - each signer of a document gets their own session and signs independently. Required when the document has more than one signer. May be omitted when it has exactly one."
          },
          "redirect_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Where the signing page sends your customer AFTER the signature completes - your own dashboard, a thank-you page. https only. Omitted, the page shows its neutral done state and the customer closes it."
          },
          "embed_origin": {
            "type": "string",
            "maxLength": 255,
            "description": "Frame this session inside your own site: the exact https origin (for example `https://app.yourbrand.com`) the page will be embedded on. The origin must first be registered under your hosted page's `embed_origins`. Omit it for an ordinary full-page session - the page then refuses to be framed anywhere."
          }
        }
      },
      "SigningSession": {
        "type": "object",
        "description": "A short-lived hosted signing session for one signature requirement. Create one when Clemta opens a signature ask (you hear requirement.created) and hand the URL to your customer - they sign inside your branded hosted page, and nobody is emailed automatically - you control delivery. Sessions are repeatable. Mint another when one expires. When the document is signed the requirement resolves and you hear requirement.fulfilled.",
        "required": [
          "object",
          "company",
          "requirement",
          "url",
          "expires_at",
          "livemode"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "signing_session"
            ]
          },
          "company": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$"
          },
          "requirement": {
            "type": "string",
            "pattern": "^rqmt_[0-9A-Za-z]{22}$"
          },
          "url": {
            "type": "string",
            "description": "Where to send your customer. The URL is the credential - treat it like a secret and pass it over a secure channel."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "livemode": {
            "type": "boolean"
          }
        }
      },
      "SupplySignerEmailBody": {
        "type": "object",
        "required": [
          "requirement",
          "signer",
          "email"
        ],
        "additionalProperties": false,
        "properties": {
          "requirement": {
            "type": "string",
            "pattern": "^rqmt_[0-9A-Za-z]{22}$",
            "description": "The open signature requirement the signer belongs to."
          },
          "signer": {
            "type": "string",
            "pattern": "^sgr_[0-9A-Za-z]{22}$",
            "description": "The deferred signer's ref (from the requirement's `signers`)."
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "description": "The signer's email. Screened for disposable domains."
          }
        }
      },
      "FixedAsset": {
        "type": "object",
        "description": "A depreciable fixed asset on a company's register. Fixed assets are the source the federal tax filing draws from: when a filing is saved, it snapshots the company's current assets. Maintain them here and the filing reflects them.",
        "required": [
          "object",
          "id",
          "number",
          "company",
          "title",
          "livemode",
          "created_at"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "fixed_asset"
            ],
            "description": "Entity name."
          },
          "id": {
            "type": "string",
            "pattern": "^fxa_[0-9A-Za-z]{22}$",
            "example": "fxa_0346sFPEvSkJvY8vt14NNw"
          },
          "number": {
            "type": "string",
            "description": "The asset's stable display number on the company register, e.g. `AST-3`."
          },
          "company": {
            "type": "string",
            "pattern": "^cmp_[0-9A-Za-z]{22}$",
            "description": "The company this asset belongs to."
          },
          "title": {
            "type": "string",
            "description": "What the asset is."
          },
          "placed_in_service": {
            "type": "string",
            "format": "date",
            "description": "The date the asset was placed in service (YYYY-MM-DD)."
          },
          "cost": {
            "type": "number",
            "format": "double",
            "description": "The asset's cost basis, in the company's currency."
          },
          "salvage_value": {
            "type": "number",
            "format": "double",
            "description": "The estimated value at the end of its useful life."
          },
          "business_use": {
            "type": "number",
            "format": "double",
            "description": "The percentage of the asset used for business (0-100)."
          },
          "depreciable_basis": {
            "type": "number",
            "format": "double",
            "readOnly": true,
            "description": "Cost minus salvage value - the amount subject to depreciation. Present only when both cost and salvage value are set. Read-only, computed."
          },
          "livemode": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "FixedAssetList": {
        "type": "object",
        "description": "A company's fixed-asset register, newest first.",
        "required": [
          "object",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FixedAsset"
            }
          }
        }
      },
      "CreateFixedAssetBody": {
        "type": "object",
        "required": [
          "title"
        ],
        "additionalProperties": false,
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "What the asset is."
          },
          "placed_in_service": {
            "type": "string",
            "format": "date",
            "description": "The date the asset was placed in service (YYYY-MM-DD)."
          },
          "cost": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "description": "The asset's cost basis."
          },
          "salvage_value": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "description": "The estimated end-of-life value. Must not exceed cost."
          },
          "business_use": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "maximum": 100,
            "description": "The percentage of the asset used for business (0-100)."
          }
        }
      },
      "UpdateFixedAssetBody": {
        "type": "object",
        "additionalProperties": false,
        "description": "Sparse update - a field left out is unchanged. Send only what you are changing.",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "placed_in_service": {
            "type": "string",
            "format": "date"
          },
          "cost": {
            "type": "number",
            "format": "double",
            "minimum": 0
          },
          "salvage_value": {
            "type": "number",
            "format": "double",
            "minimum": 0
          },
          "business_use": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "OfficerList": {
        "type": "object",
        "description": "A company's management roster of officers and directors.",
        "required": [
          "object",
          "items"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompanyOfficer"
            }
          }
        }
      },
      "HostedPageInfo": {
        "type": "object",
        "description": "The partner's hosted-page configuration: what a hosted page (identity upload, document signing) renders as its brand and legal footer. Absent fields fall back to partner_name and no links.",
        "properties": {
          "display_name": {
            "type": "string"
          },
          "support_email": {
            "type": "string"
          },
          "privacy_policy_url": {
            "type": "string"
          },
          "terms_url": {
            "type": "string"
          },
          "logo_url": {
            "type": "string",
            "description": "A servable URL for the partner's logo, when one is configured."
          },
          "icon_url": {
            "type": "string",
            "description": "A servable URL for the partner's square icon (favicon), when one is configured."
          },
          "accent_color": {
            "type": "string"
          }
        }
      },
      "SigningContext": {
        "type": "object",
        "description": "What the hosted signing page renders, read through the link's own token: the ask, your hosted-page branding, and the embedded signing session. Names only, no identifiers - the holder is your customer rather than you.",
        "required": [
          "object",
          "status"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "signing_context"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "completed",
              "canceled"
            ]
          },
          "livemode": {
            "type": "boolean",
            "description": "Whether the signature behind this link is live. A test-mode (sandbox) signature has no real document to embed, so `embed_url` is absent and the hosted page shows a test completion control instead of a signing frame. A live session carries an `embed_url` and completes inside it."
          },
          "partner_name": {
            "type": "string"
          },
          "company_name": {
            "type": "string"
          },
          "signer_name": {
            "type": "string"
          },
          "redirect_url": {
            "type": "string",
            "description": "The after-completion destination minted with the session. The page offers it once the flow completes."
          },
          "message": {
            "type": "string",
            "description": "A note to the signer, shown above the document on the hosted page - the operator's message when opening the signature. Absent when none was set."
          },
          "document_name": {
            "type": "string"
          },
          "cancel_reason": {
            "type": "string",
            "description": "Why a canceled document was voided (a signer's decline reason), to show on the canceled screen. Present only when the status is `canceled`."
          },
          "page": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HostedPageInfo"
              }
            ],
            "description": "The partner's hosted-page configuration - brand and legal footer."
          },
          "embed_url": {
            "type": "string",
            "description": "The embedded signing session the page renders, minted fresh for this page load. Present only while the ask is open."
          },
          "embed_origin": {
            "type": "string",
            "description": "The one origin allowed to frame this page, when the session was minted for embedding. The hosted page treats this as the authority and refuses to run framed anywhere else. Absent on ordinary sessions."
          },
          "others_pending": {
            "type": "boolean",
            "description": "True when this signer has completed their part but the document is not fully executed yet - other signers still have to sign. The page can then say the signature is recorded rather than that the whole document is done. It never names or counts the other signers."
          },
          "waiting_for_others": {
            "type": "boolean",
            "description": "True when the document signs in order and it is not this signer's turn yet - someone earlier in the order has still to sign. There is no embed to render, so the page shows a wait state until the earlier signer completes. It never names or counts the other signers."
          }
        }
      },
      "RequirementContext": {
        "type": "object",
        "description": "What a hosted page shows, read through the link's own token - names only, no identifiers, since the holder is your customer rather than you.",
        "required": [
          "object",
          "type",
          "status"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "requirement_context"
            ],
            "description": "Entity name."
          },
          "type": {
            "type": "string",
            "enum": [
              "document",
              "form",
              "name_change",
              "information",
              "signature"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "resolved",
              "canceled"
            ]
          },
          "partner_name": {
            "type": "string",
            "description": "The partner name a hosted page brands itself with, resolved from the link token."
          },
          "company_name": {
            "type": "string"
          },
          "owner_name": {
            "type": "string"
          },
          "page": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HostedPageInfo"
              }
            ],
            "description": "The partner's hosted-page configuration - brand and legal footer."
          },
          "message": {
            "type": "string"
          },
          "form": {
            "$ref": "#/components/schemas/ServiceOrderForm"
          },
          "embed_origin": {
            "type": "string",
            "description": "The one origin allowed to frame this page, when the session was minted for embedding. The hosted page treats this as the authority and refuses to run framed anywhere else. Absent on ordinary sessions."
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed request (e.g. unknown `Clemta-Version`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid, revoked, or grace-expired API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded, retry after the `Retry-After` header.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "The request conflicts with existing state, such as an external_id already in use or a duplicate resource.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested resource does not exist, or is not yours.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}