> ## Documentation Index > Fetch the complete documentation index at: https://docs.clemta.com/llms.txt > Use this file to discover all available pages before exploring further. # List your event stream - newest first, cursor-paged > Filter by `type`, `company_id`, or a `created_at` range. Sortable by `created_at`. ## OpenAPI ````yaml /partner/openapi.yaml get /events openapi: 3.1.0 info: title: Clemta Partner API description: | The Clemta partner surface. Authenticate with your API key as a bearer token (`Authorization: Bearer clmt_live_` or `clmt_test_`). Keys with the `clmt_test_` prefix operate in sandbox mode (`livemode: false`): test data never reaches fulfillment or billing. Versioning is date-based: pass `Clemta-Version` to pin a version, omit it to run on your account's pinned default. The effective version is echoed back on every response. 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. 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 client companies. - name: Service orders description: Order services against a company and follow their fulfilment. - name: Products description: The catalog you can offer, at your wholesale prices. - name: Tax filings description: >- Federal and state tax filings on your companies, opened by your client 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. Client KYC uploads are write-only and never listed. - name: Requirements description: >- Everything needed from you or your client - identity documents, service-order forms, Clemta's asks - as one resolvable resource. Fulfill over the API or hand your client 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 with exponential backoff over multiple days 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 days is disabled automatically and the workspace owner is emailed - no events are lost, the stream stays available on `GET /v1/events`. ## Verifying a delivery Deliveries 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. Every endpoint has its OWN signing secret (`whsec_...`), shown once when you create the endpoint. Each delivery carries three headers: - `Clemta-Webhook-Id` - the event id. Stable across retries: use it as an idempotency key so a redelivered event is processed once. - `Clemta-Webhook-Timestamp` - unix seconds of THIS attempt (a retry carries a fresh one). - `Clemta-Webhook-Signature` - a space-delimited list of `v1,` signatures. More than one while a secret rotation's overlap window is open, one per active secret. Each 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. To verify by hand: 1. 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. 2. Base64-decode your endpoint secret after the `whsec_` prefix. That is the HMAC key. 3. 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. 4. Check the timestamp is within 5 minutes of now, to reject replays. Because 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: /events: get: tags: - Events summary: List your event stream - newest first, cursor-paged description: >- Filter by `type`, `company_id`, or a `created_at` range. Sortable by `created_at`. operationId: listEvents parameters: - $ref: '#/components/parameters/EventTypeFilter' - $ref: '#/components/parameters/EventCompanyIdFilter' - $ref: '#/components/parameters/EventCreatedAtFilter' - $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' components: parameters: 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. 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 headers: ClemtaVersion: description: The API version the request was executed against. schema: type: string schemas: 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' 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. 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. 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. 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 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: $ref: '#/components/schemas/Company' service_order: $ref: '#/components/schemas/ServiceOrder' invoice: $ref: '#/components/schemas/Invoice' requirement: $ref: '#/components/schemas/Requirement' file: $ref: '#/components/schemas/File' tax_filing: $ref: '#/components/schemas/TaxFiling' calendar_event: $ref: '#/components/schemas/CalendarEvent' 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. 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 client (an open `form` requirement says which), `completed` once the final step is reached - terminal, `completed_at` is set and `service_order.completed` fires once - and `canceled`. options: type: object additionalProperties: type: string description: >- The variant choices this order was placed with (option key -> value). example: llc_members: multi_member form_required: type: boolean description: >- True when fulfilment needs a form from the client (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 wholesale 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. Invoice: type: object description: A wholesale 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 Requirement: type: object description: >- One thing needed from you or your client: 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 client. 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. message: type: string description: Why it was opened, in words you can show your client. 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 client. 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 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. 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 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 client 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 client fills it in, `in_review` once submitted to Clemta, then `accepted` or `rejected`. 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 client. `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 a draft 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 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 client. 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 description: type: string description: What is due and what happens if it is missed. 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: string format: date-time description: >- On a `calendar.reminder` event only: the reminder point that fired. Absent on calendar reads. livemode: type: boolean 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, optional, stored as contact data. 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 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 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' 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' 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 wholesale 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 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. 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 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. Relationship: type: object additionalProperties: false description: The owner's relationship to the company - role, stake, and standing. properties: title: type: string enum: - sole_owner - ceo - coo - cfo - cto - cmo - cio - hr_director - sales_director - product_manager - project_manager - software_engineer - data_analyst - ux_designer - ui_designer - operations_manager - other description: >- The owner's role, as an API token - the platform's position list. Use `other` with `custom_title` for any role outside it. custom_title: type: string maxLength: 120 pattern: ^[A-Za-z0-9 &.,:;'#-]+$ 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. Exactly one owner must be. 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: >- not_required for a company owner. required until the individual uploads it, then received. 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. 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' 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`. Optional. 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 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' 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 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 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' securitySchemes: apiKey: type: http scheme: bearer description: > Your API key, e.g. `Authorization: Bearer clmt_test_`. Live keys use the `clmt_live_` prefix. ````