Cadana Filings API

openapi: 3.0.0
info:
  description: APIs for interacting with Cadana Embedded Consumer Wallets
  version: 1.0.0
  title: Embedded Consumer Wallets Balances Filings 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: Filings
  description: Create, submit, and track statutory returns — from upcoming obligations through acceptance
paths:
  /v1/statutory/filings:
    get:
      operationId: listFilings
      x-mint:
        metadata:
          tag: Beta
      summary: List filings
      description: '**Beta** — contact Cadana to enable access for your business.


        Returns filings across all jurisdictions for a business. Use this as

        both a compliance calendar ("what''s due?") and a filing history

        ("what''s done?").


        The response includes a `summary` object with counts by status —

        use this to power compliance health dashboards without additional

        API calls.

        '
      tags:
      - Filings
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
      - name: businessId
        in: query
        schema:
          type: string
        description: Filter by business
      - name: countryCode
        in: query
        schema:
          type: string
        description: Filter by jurisdiction (ISO 3166-1 alpha-2)
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - blocked
          - in_review
          - approved
          - submitted
          - accepted
          - rejected
          - cancelled
        description: Filter by filing status
      responses:
        '200':
          description: List of filings with compliance summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FilingListItem'
                  summary:
                    $ref: '#/components/schemas/FilingSummary'
    post:
      operationId: createFiling
      x-mint:
        metadata:
          tag: Beta
      summary: Create a filing
      description: "**Beta** — contact Cadana to enable access for your business.\n\nCreates a single statutory filing. Every filing is described by a\n`breakdown` array of contribution lines that sum to the filing total.\nThe `source` field selects who's submitting the return to the\nauthority:\n\n- **`source: cadana`** (default) — Cadana will submit the return. Each\n  breakdown line must reference a `personId`. Provide `payrollRunIds`\n  as a shortcut (Cadana populates the breakdown from the tax engine)\n  or pass the `breakdown` explicitly if you computed amounts outside\n  Cadana. The filing is created in `pending` and runs the full\n  lifecycle through `accepted`. If requirements are missing, it\n  transitions to `blocked` with actionable reasons.\n- **`source: external`** — You have already filed with the authority\n  yourself. Provide the `breakdown` plus the `filingReference` (e.g.,\n  the Línea de Captura from SAT). Breakdown lines may use `personId`,\n  `externalEmployeeId`, or neither (for business-level taxes). The\n  filing is created directly in `accepted` and skips the submission\n  lifecycle. Used by the remittance-only flow.\n"
      tags:
      - Filings
      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'
  /v1/statutory/filings/batch:
    post:
      operationId: createFilingsBatch
      x-mint:
        metadata:
          tag: Beta
      summary: Create all filings for a period
      description: '**Beta** — contact Cadana to enable access for your business.


        **Not yet implemented.**


        Creates statutory filings for a business and period in a single call.

        Supports two modes:


        **Cadana payroll:** Provide `payrollRunIds` — Cadana determines which

        filing types apply based on active workers and their compensation flags

        (IMSS-eligible, INFONAVIT-eligible, etc.) and pulls amounts from the tax engine.


        **External payroll:** Provide a `filings` array with explicit amounts and

        person IDs per filing type. Use this when the client runs payroll outside

        Cadana and just needs Cadana to file and remit.


        For example, a Mexican business with 15 employees would get up to 4 filings:

        ISR, IMSS, INFONAVIT, and ISN.

        '
      tags:
      - Filings
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFilingsBatchRequest'
      responses:
        '201':
          description: Filings created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IDResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v1/statutory/filings/{filing_id}:
    get:
      operationId: getFiling
      x-mint:
        metadata:
          tag: Beta
      summary: Get a filing
      description: '**Beta** — contact Cadana to enable access for your business.


        Returns full filing details including amounts, status history,

        blocked reasons, and linked payroll runs.

        '
      tags:
      - Filings
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
      - $ref: '#/components/parameters/FilingId'
      responses:
        '200':
          description: Filing details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filing'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/statutory/filings/{filing_id}/approve:
    post:
      operationId: approveFiling
      x-mint:
        metadata:
          tag: Beta
      summary: Approve a filing for submission
      description: '**Beta** — contact Cadana to enable access for your business.


        Approves a filing, moving it from `in_review` to `approved`. Once approved,

        Cadana will submit the filing to the government authority within the

        jurisdiction''s processing window.


        Requires all requirements to be satisfied and no active blocked reasons.

        '
      tags:
      - Filings
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
      - $ref: '#/components/parameters/FilingId'
      responses:
        '204':
          description: Filing approved
        '409':
          description: Filing cannot be approved (requirements unsatisfied or invalid state)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/statutory/filings/{filing_id}/cancel:
    post:
      operationId: cancelFiling
      x-mint:
        metadata:
          tag: Beta
      summary: Cancel a filing
      description: '**Beta** — contact Cadana to enable access for your business.


        Cancels a filing that has not yet been submitted. Cannot cancel filings

        that are already submitted, accepted, or rejected.

        '
      tags:
      - Filings
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
      - $ref: '#/components/parameters/FilingId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Optional reason for cancellation
      responses:
        '204':
          description: Filing cancelled
        '409':
          description: Filing cannot be cancelled in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/statutory/filings/{filing_id}/amend:
    post:
      operationId: amendFiling
      x-mint:
        metadata:
          tag: Beta
      summary: Amend a previously accepted filing
      description: '**Beta** — contact Cadana to enable access for your business.


        **Not yet implemented.**


        Creates an amendment filing linked to the original. The original filing''s

        status remains `accepted` and gains an `amended_by` reference. The new

        amendment filing starts in `pending` status.

        '
      tags:
      - Filings
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
      - $ref: '#/components/parameters/FilingId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmendFilingRequest'
      responses:
        '201':
          description: Amendment filing created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDResponse'
        '409':
          description: Original filing is not in a state that can be amended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/statutory/filings/{filing_id}/document:
    get:
      operationId: getFilingDocument
      x-mint:
        metadata:
          tag: Beta
      summary: Download filing document
      description: '**Beta** — contact Cadana to enable access for your business.


        **Not yet implemented.**


        Returns a signed URL to download the filing document (PDF). Only available

        after the filing has been submitted.

        '
      tags:
      - Filings
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
      - $ref: '#/components/parameters/FilingId'
      responses:
        '200':
          description: Filing document download URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                    description: Signed download URL (expires in 15 minutes)
                  expiresAt:
                    type: string
                    format: date-time
        '404':
          description: Document not yet available
  /v1/statutory/compliance/summary:
    get:
      operationId: getComplianceSummary
      x-mint:
        metadata:
          tag: Beta
      summary: Get compliance health summary
      description: '**Beta** — contact Cadana to enable access for your business.


        **Not yet implemented.**


        Returns a single-call overview of the business''s entire statutory

        compliance posture across all jurisdictions. Includes filing counts by

        status, remittance totals, upcoming deadlines, and outstanding

        requirements.


        This is the "how are we doing?" endpoint — designed to power compliance

        dashboards without needing multiple API calls.

        '
      tags:
      - Filings
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
      - name: businessId
        in: query
        required: true
        schema:
          type: string
      - name: countryCode
        in: query
        schema:
          type: string
        description: Filter to a specific jurisdiction
      responses:
        '200':
          description: Compliance health summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceSummary'
components:
  schemas:
    IDResponse:
      type: object
      description: Response containing the ID of a newly created resource.
      properties:
        id:
          type: string
          example: fil_01HQ3K4N7XYZABC
    StatusHistoryEntry:
      type: object
      description: Records a single status transition on a filing or remittance.
      properties:
        from:
          type: string
          description: Previous status
          example: pending
        to:
          type: string
          description: New status
          example: in_review
        timestamp:
          type: number
          format: epoch
          description: Unix epoch timestamp of the transition
          example: 1709654400
    FilingListItem:
      type: object
      description: 'Reduced filing entry returned in list responses. Use

        `GET /v1/statutory/filings/{id}` for full details.

        '
      properties:
        id:
          type: string
          example: fil_01HQ3K4N7XYZABC
        businessId:
          type: string
          example: biz_01HQ3K4N7XYZABC
        countryCode:
          type: string
          example: MX
        source:
          type: string
          enum:
          - cadana
          - external
          description: Whether Cadana prepared the filing (`cadana`) or you filed externally and provided the data (`external`).
          example: cadana
        filingTypeId:
          type: string
          example: ft_mx_isr_monthly
        filingTypeName:
          type: string
          example: ISR Withholding
        authorityName:
          type: string
          example: SAT
        status:
          type: string
          enum:
          - pending
          - blocked
          - in_review
          - approved
          - submitted
          - accepted
          - rejected
          - cancelled
        period:
          type: object
          properties:
            start:
              type: string
              format: date
            end:
              type: string
              format: date
            label:
              type: string
        dueAt:
          type: string
          example: '2026-02-10'
        workerCount:
          type: integer
          example: 15
        createdAt:
          type: number
          format: epoch
          example: 1709280000
        updatedAt:
          type: number
          format: epoch
          example: 1709280000
    AmendFilingRequest:
      type: object
      required:
      - reason
      properties:
        reason:
          type: string
          description: Reason for the amendment
        correctedAmounts:
          $ref: '#/components/schemas/FilingAmounts'
    ComplianceSummary:
      type: object
      description: Single-call compliance health overview
      properties:
        businessId:
          type: string
        asOf:
          type: string
          format: date-time
          description: Timestamp of this summary
        filings:
          type: object
          properties:
            total:
              type: integer
            byStatus:
              type: object
              properties:
                pending:
                  type: integer
                blocked:
                  type: integer
                in_review:
                  type: integer
                approved:
                  type: integer
                submitted:
                  type: integer
                accepted:
                  type: integer
                rejected:
                  type: integer
        remittances:
          type: object
          properties:
            pendingCount:
              type: integer
            pendingAmount:
              type: number
              format: decimal
              description: Total amount awaiting remittance (in USD equivalent)
            completedThisMonth:
              type: integer
            completedAmountThisMonth:
              type: number
              format: decimal
        requirements:
          type: object
          properties:
            outstanding:
              type: integer
            byCategory:
              type: object
              properties:
                businessRegistration:
                  type: integer
                businessDocument:
                  type: integer
                businessTaxParameter:
                  type: integer
                workerData:
                  type: integer
        nextDeadlines:
          type: array
          description: Next 5 upcoming deadlines across all jurisdictions
          items:
            type: object
            properties:
              filingId:
                type: string
              filingTypeName:
                type: string
              countryCode:
                type: string
              dueAt:
                type: string
                format: date-time
              status:
                type: string
        jurisdictions:
          type: array
          description: Per-country breakdown
          items:
            type: object
            properties:
              countryCode:
                type: string
              countryName:
                type: string
              workerCount:
                type: integer
              filingsCompleted:
                type: integer
              filingsTotal:
                type: integer
              requirementsOutstanding:
                type: integer
    CreateFilingRequest:
      type: object
      required:
      - businessId
      - countryCode
      - filingTypeId
      - periodStart
      - periodEnd
      - currency
      description: "Create a filing. Every filing is described by a `breakdown` array of\ncontribution lines that sum to the filing total — the breakdown is the\ncanonical input. The `source` field selects who's filing with the\nauthority:\n\n**`source: cadana`** (default) — Cadana prepares and submits the return\nto the authority. Each `breakdown` line must reference a `personId`.\nYou can either:\n- Provide `payrollRunIds` and Cadana auto-populates the breakdown from\n  the tax engine, or\n- Provide the `breakdown` array yourself if you computed the amounts\n  outside Cadana but want Cadana to file.\n\n**`source: external`** — You have already filed the return with the\nauthority yourself; you're sending Cadana the breakdown plus the\n`filingReference` (e.g., the Línea de Captura from SAT) so a remittance\ncan be created against it. Breakdown lines may use `personId`,\n`externalEmployeeId`, or neither (for business-level taxes like\nMexico's ISN). The filing is created directly in `accepted`.\n"
      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`.

            '
    Filing:
      type: object
      description: 'Full filing detail returned by `GET /v1/statutory/filings/{id}`.

        Includes amounts, status history, and linked payroll runs.

        '
      properties:
        id:
          type: string
          example: fil_01HQ3K4N7XYZABC
        businessId:
          type: string
          example: biz_01HQ3K4N7XYZABC
        countryCode:
          type: string
          example: MX
        source:
          type: string
          enum:
          - cadana
          - external
          description: "How the filing data was sourced.\n\n- `cadana` — Cadana prepared and submitted the return to the authority.\n  The filing runs the full lifecycle (`pending → in_review → approved →\n  submitted → accepted`).\n- `external` — You filed the return with the authority yourself and\n  submitted the resulting totals + `filingReference` to Cadana so a\n  remittance can be created against it. External filings are created\n  directly in `accepted` and do not run the submission lifecycle.\n"
          example: cadana
        filingTypeId:
          type: string
          description: Filing type identifier (from jurisdiction filing types)
          example: ft_mx_isr_monthly
        filingTypeName:
          type: string
          description: Human-readable filing type name
          example: ISR Withholding
        authorityId:
          type: string
          description: Government authority identifier
          example: auth_mx_sat
        authorityName:
          type: string
          description: Government authority name
          example: SAT
        filingReference:
          type: string
          nullable: true
          description: 'Government-issued reference for this filing. The exact term varies by

            country: **Línea de Captura** in Mexico, **acuse de recibo** for some

            SAT receipts, **challan number** in India, **BRN** in Nigeria,

            **NPC** in some others.


            For `source: external` filings this is required at creation time —

            it''s what the receiving bank or authority uses to attribute the

            remittance payment to the filing. For `source: cadana` filings

            Cadana populates this once the authority confirms receipt.

            '
          example: 0123456ABCD7890EF
        status:
          type: string
          enum:
          - pending
          - blocked
          - in_review
          - approved
          - submitted
          - accepted
          - rejected
          - cancelled
          description: 'Filing lifecycle for `source: cadana`: pending → in_review → approved → submitted → accepted. Filings can become blocked at pending or in_review if data is missing, and return to pending once resolved. Rejected filings return to pending for correction. Any pre-submit state can be cancelled.


            For `source: external` filings, the filing is created directly in `accepted` and stays there — there is no submission step for Cadana to run because you already filed with the authority.

            '
        period:
          type: object
          properties:
            start:
              type: string
              format: date
              example: '2026-01-01'
            end:
              type: string
              format: date
              example: '2026-01-31'
            label:
              type: string
              example: January 2026
        dueAt:
          type: string
          description: Deadline for submission to the authority
          example: '2026-02-10'
        amounts:
          $ref: '#/components/schemas/FilingAmounts'
        workerCount:
          type: integer
          description: 'Number of distinct workers in the filing''s `breakdown` (counted via

            `personId` or `externalEmployeeId`). Zero for purely business-level

            filings.

            '
          example: 15
        payrollRunIds:
          type: array
          items:
            type: string
          description: Linked Cadana payroll runs (when populated via a payroll-run shortcut)
        breakdown:
          type: array
          description: 'Per-employee contribution lines that roll up into the filing total.

            For `source: cadana` filings Cadana populates this from payroll;

            for `source: external` you provide it at creation time.

            '
          items:
            $ref: '#/components/schemas/FilingBreakdownEntry'
        blockedReasons:
          type: array
          items:
            type: string
          description: 'Human-readable reasons why this filing is blocked. Present when

            status is `blocked`. Reasons auto-clear when the underlying data

            is submitted.

            '
          example:
          - Missing worker RFC for per_01ABC
          - Business IMSS registration not found
        statusHistory:
          type: array
          items:
            $ref: '#/components/schemas/StatusHistoryEntry'
        createdAt:
          type: number
          format: epoch
          description: Unix epoch timestamp
          example: 1709280000
        updatedAt:
          type: number
          format: epoch
          description: Unix epoch timestamp
          example: 1709280000
    FilingBreakdownEntry:
      type: object
      description: "One contribution line that rolls up into a filing's total. The breakdown\narray as a whole is the canonical description of the filing — its sum is\nthe filing total.\n\n**Identifying the worker:**\n- For `source: cadana` filings, each line must reference a `personId`\n  (Cadana needs the worker record to populate filing fields).\n- For `source: external` filings, lines may use `personId` (when the\n  worker is onboarded), `externalEmployeeId` (when not), or neither\n  (for business-level taxes computed on aggregate payroll, like\n  Mexico's ISN, where there's no per-worker allocation).\n"
      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
    FilingAmounts:
      type: object
      description: 'Derived totals for the filing. **Read-only on responses** — Cadana

        computes these values from the `breakdown` lines. You do not pass

        `amounts` when creating a filing; provide the `breakdown` array and

        the total falls out automatically.

        '
      properties:
        currency:
          type: string
          description: ISO 4217 currency code. Set on the filing at creation time.
          example: MXN
        total:
          type: number
          format: decimal
          description: Sum of `amount` across every line in the filing's breakdown.
          example: 82345
    FilingSummary:
      type: object
      description: 'Status counts for the filtered set of filings. Use this to power

        compliance health dashboards.

        '
      properties:
        total:
          type: integer
        pending:
          type: integer
        inReview:
          type: integer
        approved:
          type: integer
        submitted:
          type: integer
        accepted:
          type: integer
        blocked:
          type: integer
        cancelled:
          type: integer
        rejected:
          type: integer
    CreateFilingsBatchRequest:
      type: object
      required:
      - businessId
      - periodStart
      - periodEnd
      description: "Batch create filings for a business and period in one call. Pick one\ninput shape:\n\n- **`payrollRunIds`** — Cadana derives the filing types and breakdowns\n  from the linked Cadana payroll runs. Each filing is created as\n  `source: cadana` and runs the full lifecycle.\n- **`filings`** — Provide an explicit array, each entry with its own\n  `filingTypeId`, `currency`, and `breakdown`. Each entry can be\n  `source: cadana` (Cadana files for you) or `source: external` (you\n  already filed and supply a `filingReference`). Use this when amounts\n  were computed outside Cadana.\n\nExactly one of `payrollRunIds` or `filings` must be provided.\n"
      properties:
        businessId:
          type: string
        periodStart:
          type: string
          format: date
          example: '2026-02-01'
        periodEnd:
          type: string
          format: date
          example: '2026-02-28'
        payrollRunIds:
          type: array
          items:
            type: string
          description: 'Link to Cadana payroll runs. Cadana auto-determines filing types

            and populates amounts from the tax engine.

            Mutually exclusive with `filings`.

            '
        filings:
          type: array
          description: 'Explicit per-filing data. Use this when you computed the amounts

            outside Cadana — works for both `source: cadana` (Cadana still

            files) and `source: external` (you already filed). Mutually

            exclusive with `payrollRunIds`.

            '
          items:
            type: object
            required:
            - filingTypeId
            - currency
            - breakdown
            properties:
              filingTypeId:
                type: string
                example: ft_mx_isr_monthly
              source:
                type: string
                enum:
                - cadana
                - external
                default: cadana
              currency:
                type: string
                description: ISO 4217 currency code applied to every breakdown line.
                example: MXN
              filingReference:
                type: string
                description: Required when this entry's `source` is `external`.
                example: 0123456ABCD7890EF
              breakdown:
                type: array
                items:
                  $ref: '#/components/schemas/FilingBreakdownEntry'
        countryCode:
          type: string
          description: 'Limit to a specific jurisdiction. If omitted, creates filings

            for all jurisdictions where the business has active workers.

            '
        filingTypeIds:
          type: array
          items:
            type: string
          description: 'Limit to specific filing types (only applies when using

            `payrollRunIds` mode). If omitted, creates all applicable

   

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cadana/refs/heads/main/openapi/cadana-filings-api-openapi.yml