> ## Documentation Index > Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a filing > **Beta** — contact Cadana to enable access for your business. Creates a single statutory filing. Every filing is described by a `breakdown` array of contribution lines that sum to the filing total. The `source` field selects who's submitting the return to the authority: - **`source: cadana`** (default) — Cadana will submit the return. Each breakdown line must reference a `personId`. Provide `payrollRunIds` as a shortcut (Cadana populates the breakdown from the tax engine) or pass the `breakdown` explicitly if you computed amounts outside Cadana. The filing is created in `pending` and runs the full lifecycle through `accepted`. If requirements are missing, it transitions to `blocked` with actionable reasons. - **`source: external`** — You have already filed with the authority yourself. Provide the `breakdown` plus the `filingReference` (e.g., the Línea de Captura from SAT). Breakdown lines may use `personId`, `externalEmployeeId`, or neither (for business-level taxes). The filing is created directly in `accepted` and skips the submission lifecycle. Used by the remittance-only flow. ## OpenAPI ````yaml /openapi/statutory-compliance.yaml post /v1/statutory/filings openapi: 3.0.0 info: title: Statutory Compliance API version: 0.1.0 description: Statutory filing, government remittance, and compliance tracking API termsOfService: https://cadanapay.com/terms-and-conditions contact: email: api@cadanapay.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.cadanapay.com description: Prod Server - url: https://dev-api.cadanapay.com description: Dev Server security: - Authorization: [] tags: - name: Jurisdictions description: Discover supported countries, required fields, and filing types - name: Filings description: >- Create, submit, and track statutory returns — from upcoming obligations through acceptance - name: Remittances description: Government payments linked to filings - name: Requirements description: Prerequisites that must be satisfied before filing - name: Events description: Immutable audit trail - name: Statutory Fields description: Submit and read entity-level statutory filing data paths: /v1/statutory/filings: post: tags: - Filings summary: Create a filing description: | **Beta** — contact Cadana to enable access for your business. Creates a single statutory filing. Every filing is described by a `breakdown` array of contribution lines that sum to the filing total. The `source` field selects who's submitting the return to the authority: - **`source: cadana`** (default) — Cadana will submit the return. Each breakdown line must reference a `personId`. Provide `payrollRunIds` as a shortcut (Cadana populates the breakdown from the tax engine) or pass the `breakdown` explicitly if you computed amounts outside Cadana. The filing is created in `pending` and runs the full lifecycle through `accepted`. If requirements are missing, it transitions to `blocked` with actionable reasons. - **`source: external`** — You have already filed with the authority yourself. Provide the `breakdown` plus the `filingReference` (e.g., the Línea de Captura from SAT). Breakdown lines may use `personId`, `externalEmployeeId`, or neither (for business-level taxes). The filing is created directly in `accepted` and skips the submission lifecycle. Used by the remittance-only flow. operationId: createFiling parameters: - $ref: '#/components/parameters/XMultiTenantKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateFilingRequest' responses: '201': description: Filing created content: application/json: schema: $ref: '#/components/schemas/IDResponse' '400': $ref: '#/components/responses/BadRequest' '422': $ref: '#/components/responses/UnprocessableEntity' components: parameters: XMultiTenantKey: name: X-MultiTenantKey in: header required: false schema: type: string description: >- Required when using a Platform API token. The tenant key identifying which business to operate on. schemas: CreateFilingRequest: type: object required: - businessId - countryCode - filingTypeId - periodStart - periodEnd - currency description: | Create a filing. Every filing is described by a `breakdown` array of contribution lines that sum to the filing total — the breakdown is the canonical input. The `source` field selects who's filing with the authority: **`source: cadana`** (default) — Cadana prepares and submits the return to the authority. Each `breakdown` line must reference a `personId`. You can either: - Provide `payrollRunIds` and Cadana auto-populates the breakdown from the tax engine, or - Provide the `breakdown` array yourself if you computed the amounts outside Cadana but want Cadana to file. **`source: external`** — You have already filed the return with the authority yourself; you're sending Cadana the breakdown plus the `filingReference` (e.g., the Línea de Captura from SAT) so a remittance can be created against it. Breakdown lines may use `personId`, `externalEmployeeId`, or neither (for business-level taxes like Mexico's ISN). The filing is created directly in `accepted`. properties: businessId: type: string countryCode: type: string description: ISO 3166-1 alpha-2 country code example: MX source: type: string enum: - cadana - external default: cadana description: | Who's responsible for submitting the return to the authority. `cadana` (default) means Cadana submits; `external` means you already submitted it and are providing the resulting data so Cadana can remit. example: external filingTypeId: type: string description: The type of filing (from jurisdiction filing types) example: ft_mx_isr_monthly periodStart: type: string format: date periodEnd: type: string format: date currency: type: string description: | ISO 4217 currency code that applies to every `amount` in the breakdown. Must match the filing-type's jurisdiction currency. example: MXN filingReference: type: string description: > Government-issued reference for this filing. **Required when `source: external`** — this is the value the receiving bank or authority uses to attribute your remittance payment. Country-specific naming: Línea de Captura (MX), challan number (IN), BRN (NG). Ignored when `source: cadana`; Cadana populates it once the authority confirms receipt. example: 0123456ABCD7890EF breakdown: type: array description: | Contribution lines that sum to the filing total. **Required**, with one exception: omit when `source: cadana` and `payrollRunIds` is provided — Cadana auto-populates the breakdown from the tax engine in that case. items: $ref: '#/components/schemas/FilingBreakdownEntry' payrollRunIds: type: array items: type: string description: | `source: cadana` shortcut. Link to Cadana payroll runs whose tax calculations feed this filing — Cadana auto-populates the `breakdown` from the tax engine results. Ignored when `source: external`. IDResponse: type: object description: Response containing the ID of a newly created resource. properties: id: type: string example: fil_01HQ3K4N7XYZABC FilingBreakdownEntry: type: object description: | One contribution line that rolls up into a filing's total. The breakdown array as a whole is the canonical description of the filing — its sum is the filing total. **Identifying the worker:** - For `source: cadana` filings, each line must reference a `personId` (Cadana needs the worker record to populate filing fields). - For `source: external` filings, lines may use `personId` (when the worker is onboarded), `externalEmployeeId` (when not), or neither (for business-level taxes computed on aggregate payroll, like Mexico's ISN, where there's no per-worker allocation). required: - amount properties: personId: type: string description: | Cadana person ID. Required on `source: cadana` filings. example: per_01HQ3K4N7XYZABC externalEmployeeId: type: string description: | Your own employee identifier. Use on `source: external` filings when the worker is not onboarded into Cadana. example: EMP-00142 employeeName: type: string description: Human-readable name for audit trail and reconciliation. example: María García López amount: type: number format: decimal description: Contribution amount for this line in the filing currency. example: 4250 Error: type: object properties: error: type: object properties: code: type: string example: invalid_request message: type: string example: countryCode is required details: type: array nullable: true items: type: object properties: field: type: string message: type: string responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: Request understood but cannot be processed content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: Authorization: type: http scheme: bearer bearerFormat: API_SECRET_KEY ````