Skip to main content
POST
/
v1
/
statutory
/
filings
Create a filing
curl --request POST \
  --url https://api.cadanapay.com/v1/statutory/filings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "businessId": "<string>",
  "filingTypeId": "ft_mx_isr_monthly",
  "periodStart": "2023-12-25",
  "periodEnd": "2023-12-25",
  "payrollRunIds": [
    "<string>"
  ],
  "amounts": {
    "currency": "MXN",
    "totalTax": 45000,
    "employerContributions": 20000,
    "employeeDeductions": 25000,
    "penalties": 0,
    "lineItems": [
      {
        "description": "ISR - Withholding per Artículo 96 table",
        "amount": 12500,
        "legislativeReference": "LISR, Artículo 96, Tabla mensual"
      }
    ]
  },
  "personIds": [
    "<string>"
  ],
  "metadata": {}
}
'
{
  "id": "fil_01HQ3K4N7XYZABC",
  "businessId": "biz_01HQ3K4N7XYZABC",
  "countryCode": "MX",
  "filingType": {
    "id": "ft_mx_isr_monthly",
    "name": "ISR Withholding",
    "description": "ISR income tax withholding return filed monthly with SAT",
    "governmentFormName": "Declaración Provisional ISR",
    "authority": {
      "id": "auth_mx_sat",
      "name": "Servicio de Administración Tributaria",
      "abbreviation": "SAT",
      "countryCode": "MX",
      "electronicSystem": "Portal del SAT"
    },
    "frequency": "MONTHLY",
    "dueDay": 10,
    "includesRemittance": true,
    "legislativeReference": "Ley del Impuesto Sobre la Renta (LISR), Artículo 96"
  },
  "status": "upcoming",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-31",
    "label": "January 2026"
  },
  "dueAt": "2026-02-10T23:59:59Z",
  "filedAt": "2023-11-07T05:31:56Z",
  "amounts": {
    "currency": "MXN",
    "totalTax": 45000,
    "employerContributions": 20000,
    "employeeDeductions": 25000,
    "penalties": 0,
    "lineItems": [
      {
        "description": "ISR - Withholding per Artículo 96 table",
        "amount": 12500,
        "legislativeReference": "LISR, Artículo 96, Tabla mensual"
      }
    ]
  },
  "blockedReasons": [
    {
      "code": "missing_tax_id",
      "message": "SAT RFC (Registro Federal de Contribuyentes) is required for the business",
      "requirementId": "req_01HQ3K4N7XYZABC",
      "resourceType": "business",
      "resourceId": "<string>",
      "affectedField": "taxId"
    }
  ],
  "personIds": [
    "per_01ABC",
    "per_02DEF",
    "per_03GHI"
  ],
  "remittanceId": "<string>",
  "amends": "<string>",
  "amendedBy": "<string>",
  "document": {
    "url": "<string>",
    "generatedAt": "2023-11-07T05:31:56Z"
  },
  "statusHistory": [
    {
      "status": "<string>",
      "changedAt": "2023-11-07T05:31:56Z",
      "actor": "<string>",
      "blockedReasons": [
        {
          "code": "missing_tax_id",
          "message": "SAT RFC (Registro Federal de Contribuyentes) is required for the business",
          "requirementId": "req_01HQ3K4N7XYZABC",
          "resourceType": "business",
          "resourceId": "<string>",
          "affectedField": "taxId"
        }
      ]
    }
  ],
  "workerCount": 15,
  "estimatedAmount": {
    "currency": "<string>",
    "amount": 123
  },
  "legislativeReferences": [
    "Ley del Impuesto Sobre la Renta (LISR), Artículo 96",
    "Resolución Miscelánea Fiscal, Regla 2.7.5.2"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create a filing. Two modes:

Mode 1 — Cadana payroll: Provide payroll_run_ids and Cadana pulls the calculated amounts from the tax engine automatically.

Mode 2 — External payroll: Provide amounts directly with the filing data. Use this when the client runs payroll outside Cadana and just needs filing + remittance.

At least one of payroll_run_ids or amounts must be provided.

​
businessId
string
required
​
filingTypeId
string
required

The type of filing (from jurisdiction filing types)

Example:

"ft_mx_isr_monthly"

​
periodStart
string<date>
required
​
periodEnd
string<date>
required
​
payrollRunIds
string[]

Link to Cadana payroll runs whose tax calculations feed this filing. Cadana auto-populates amounts from the tax engine results. Mutually exclusive with amounts.

​
amounts
object

Provide filing amounts directly when payroll was run externally. Must include at minimum: currency, total_tax, and line_items. Mutually exclusive with payroll_run_ids.

​
personIds
string[]

Person IDs included in this filing. Required when providing amounts directly (so Cadana can validate worker data). Auto-populated from payroll run when using payroll_run_ids.

​
metadata
object

Response

Filing created

​
id
string
Example:

"fil_01HQ3K4N7XYZABC"

​
businessId
string
Example:

"biz_01HQ3K4N7XYZABC"

​
countryCode
string
Example:

"MX"

​
filingType
object

A type of statutory return that must be filed in a jurisdiction. Filing types vary by country — use GET /jurisdictions/{countryCode}/filing-types to retrieve them.

​
status
enum<string>

Filing lifecycle:

upcoming ──→ pending ──→ in_review ──→ approved ──→ submitted ──→ accepted
                │            │                         │             │
                ▼            ▼                         ▼             ▼
             blocked     blocked                   rejected      amended
                │            │                         │
                ▼            ▼                         ▼
             pending     pending                    pending (retry)

Any pre-submit state ──→ cancelled
  • upcoming — Filing obligation exists (based on workers/jurisdiction) but payroll hasn't run yet. Unbundled clients skip this state entirely.
  • pending — Filing created with amounts, being validated.
  • blocked — Missing data or requirements prevent submission.
  • in_review — Validated, ready for approval.
  • approved — Approved, queued for submission to authority.
  • submitted — Sent to the government authority.
  • accepted — Authority acknowledged receipt.
  • rejected — Authority rejected the filing.
  • amended — Superseded by a correction filing.
  • cancelled — Cancelled before submission.
Available options:
upcoming,
pending,
blocked,
in_review,
approved,
submitted,
accepted,
rejected,
amended,
cancelled
​
period
object
​
dueAt
string<date-time>

Deadline for submission to the authority

Example:

"2026-02-10T23:59:59Z"

​
filedAt
string<date-time> | null

When the authority acknowledged receipt

​
amounts
object

Financial breakdown of the filing

​
blockedReasons
object[] | null

Present when status is blocked

​
personIds
string[]

Person IDs (from the Persons Service) included in this filing. These reference workers whose tax deductions are reported in this return. Person data (taxId, nationalId, compensation, etc.) is read from the Persons Service at filing preparation time — not duplicated here.

Example:
["per_01ABC", "per_02DEF", "per_03GHI"]
​
remittanceId
string | null

Linked remittance (when payment has been initiated)

​
amends
string | null

ID of the original filing this amends

​
amendedBy
string | null

ID of the filing that supersedes this one

​
document
object

The filing document, available after submission

​
statusHistory
object[]
​
workerCount
integer

Number of workers included in this filing. For upcoming filings, this is the count of eligible persons in the jurisdiction.

Example:

15

​
estimatedAmount
object

Estimated filing amount. Present on upcoming filings before exact amounts are calculated. Null once amounts is populated.

​
legislativeReferences
string[]

Legal citations for this filing

Example:
[
  "Ley del Impuesto Sobre la Renta (LISR), Artículo 96",
  "Resolución Miscelánea Fiscal, Regla 2.7.5.2"
]
​
createdAt
string<date-time>
​
updatedAt
string<date-time>