Create a filing

Creates a single statutory filing. Supports two modes:

• Cadana payroll: Provide payrollRunIds — amounts are pulled from the tax engine automatically.
• External payroll: Provide amounts and personIds directly — use this when the client runs payroll outside Cadana and just needs Cadana to file and remit.

The filing is created in pending status. If requirements are missing, it transitions to blocked with actionable reasons.

POST /v1/statutory/filings

Create a filing

cURL

curl --request POST \
  --url https://api.cadanapay.com/v1/statutory/filings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "businessId": "<string>",
  "countryCode": "MX",
  "filingTypeId": "ft_mx_isr_monthly",
  "periodStart": "2023-12-25",
  "periodEnd": "2023-12-25",
  "payrollRunIds": [
    "<string>"
  ],
  "amounts": {
    "currency": "MXN",
    "totalTax": 45000,
    "employerContributions": 20000,
    "employeeDeductions": 25000,
    "lineItems": [
      {
        "description": "ISR - Withholding per Artículo 96 table",
        "amount": 12500
      }
    ]
  },
  "personIds": [
    "<string>"
  ]
}
'

201

{
  "id": "fil_01HQ3K4N7XYZABC"
}

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 payrollRunIds 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 payrollRunIds or amounts must be provided.

businessId · string · required

countryCode · string · required

ISO 3166-1 alpha-2 country code

Example:

"MX"

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

Financial breakdown of the filing

Show child attributes

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 payrollRunIds.

Response

201

application/json

Filing created

Response containing the ID of a newly created resource.

id · string

Example:

"fil_01HQ3K4N7XYZABC"