> ## 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. # Submit a tax filing > 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. ## OpenAPI ````yaml /partner/openapi.yaml post /companies/{companyID}/tax-filings/{filingID}/submit 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: /companies/{companyID}/tax-filings/{filingID}/submit: post: tags: - Tax filings 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. operationId: submitTaxFiling 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' components: parameters: 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 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 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' headers: ClemtaVersion: description: The API version the request was executed against. schema: type: string schemas: 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 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 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. 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' 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 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: Unauthorized: description: Missing, invalid, revoked, or grace-expired API key. 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' 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. ````