Skip to main content
POST
/
v1
/
statutory
/
filings
/
batch
Create all filings for a period
curl --request POST \
  --url https://api.cadanapay.com/v1/statutory/filings/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "businessId": "<string>",
  "periodStart": "2026-02-01",
  "periodEnd": "2026-02-28",
  "payrollRunIds": [
    "<string>"
  ],
  "filings": [
    {
      "filingTypeId": "ft_mx_isr_monthly",
      "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>"
      ]
    }
  ],
  "countryCode": "<string>",
  "filingTypeIds": [
    "<string>"
  ]
}
'
{
  "data": [
    {
      "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"
    }
  ],
  "skipped": [
    {
      "filingTypeId": "<string>",
      "reason": "No workers with pensionable flag enabled"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json

Batch create filings. Two modes:

Mode 1 — Cadana payroll: Provide payroll_run_ids and Cadana auto-determines filing types and amounts from the tax engine.

Mode 2 — External payroll: Provide filings array with explicit amounts per filing type. Use this when the client runs payroll outside Cadana and provides the data directly.

One of payroll_run_ids or filings must be provided.

​
businessId
string
required
​
periodStart
string<date>
required
Example:

"2026-02-01"

​
periodEnd
string<date>
required
Example:

"2026-02-28"

​
payrollRunIds
string[]

Link to Cadana payroll runs. Cadana auto-determines filing types and populates amounts from the tax engine. Mutually exclusive with filings.

​
filings
object[]

Explicit filing data for external payroll. Each entry specifies the filing type, amounts, and workers. Use this when payroll was run outside Cadana. Mutually exclusive with payroll_run_ids.

​
countryCode
string

Limit to a specific jurisdiction. If omitted, creates filings for all jurisdictions where the business has active workers.

​
filingTypeIds
string[]

Limit to specific filing types (only applies when using payroll_run_ids mode). If omitted, creates all applicable filing types based on worker flags.

Response

Filings created

​
data
object[]
​
skipped
object[]

Filing types that were skipped (no applicable workers)