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>",
  "countryCode": "MX",
  "filingTypeId": "ft_mx_isr_monthly",
  "periodStart": "2023-12-25",
  "periodEnd": "2023-12-25",
  "currency": "MXN",
  "source": "external",
  "filingReference": "0123456ABCD7890EF",
  "breakdown": [
    {
      "amount": 4250,
      "personId": "per_01HQ3K4N7XYZABC",
      "externalEmployeeId": "EMP-00142",
      "employeeName": "María García López"
    }
  ],
  "payrollRunIds": [
    "<string>"
  ]
}
'
{
  "id": "fil_01HQ3K4N7XYZABC"
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
X-MultiTenantKey
string

Required when using a Platform API token. The tenant key identifying which business to operate on.

Body

application/json

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.

​
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
​
currency
string
required

ISO 4217 currency code that applies to every amount in the breakdown. Must match the filing-type's jurisdiction currency.

Example:

"MXN"

​
source
enum<string>
default:cadana

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.

Available options:
cadana,
external
Example:

"external"

​
filingReference
string

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
object[]

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.

​
payrollRunIds
string[]

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.

Response

Filing created

Response containing the ID of a newly created resource.

​
id
string
Example:

"fil_01HQ3K4N7XYZABC"