Create all filings for a period

Beta — contact Cadana to enable access for your business.

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.

All filings in one batch must share the same source — a batch is either all cadana or all external; mixing sources returns 400.

For example, a Mexican business with 15 employees would get up to 4 filings: ISR, IMSS, INFONAVIT, and ISN.

POST /v1/statutory/filings/batch

Create all filings for a period

cURL

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",
      "currency": "MXN",
      "breakdown": [
        {
          "amount": 4250,
          "personId": "per_01HQ3K4N7XYZABC",
          "externalEmployeeId": "EMP-00142",
          "employeeName": "María García López"
        }
      ],
      "source": "cadana",
      "filingReference": "0123456ABCD7890EF"
    }
  ],
  "countryCode": "<string>",
  "filingTypeIds": [
    "<string>"
  ]
}
'

import requests

url = "https://api.cadanapay.com/v1/statutory/filings/batch"

payload = {
    "businessId": "<string>",
    "periodStart": "2026-02-01",
    "periodEnd": "2026-02-28",
    "payrollRunIds": ["<string>"],
    "filings": [
        {
            "filingTypeId": "ft_mx_isr_monthly",
            "currency": "MXN",
            "breakdown": [
                {
                    "amount": 4250,
                    "personId": "per_01HQ3K4N7XYZABC",
                    "externalEmployeeId": "EMP-00142",
                    "employeeName": "María García López"
                }
            ],
            "source": "cadana",
            "filingReference": "0123456ABCD7890EF"
        }
    ],
    "countryCode": "<string>",
    "filingTypeIds": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    businessId: '<string>',
    periodStart: '2026-02-01',
    periodEnd: '2026-02-28',
    payrollRunIds: ['<string>'],
    filings: [
      {
        filingTypeId: 'ft_mx_isr_monthly',
        currency: 'MXN',
        breakdown: [
          {
            amount: 4250,
            personId: 'per_01HQ3K4N7XYZABC',
            externalEmployeeId: 'EMP-00142',
            employeeName: 'María García López'
          }
        ],
        source: 'cadana',
        filingReference: '0123456ABCD7890EF'
      }
    ],
    countryCode: '<string>',
    filingTypeIds: ['<string>']
  })
};

fetch('https://api.cadanapay.com/v1/statutory/filings/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadanapay.com/v1/statutory/filings/batch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'businessId' => '<string>',
    'periodStart' => '2026-02-01',
    'periodEnd' => '2026-02-28',
    'payrollRunIds' => [
        '<string>'
    ],
    'filings' => [
        [
                'filingTypeId' => 'ft_mx_isr_monthly',
                'currency' => 'MXN',
                'breakdown' => [
                                [
                                                                'amount' => 4250,
                                                                'personId' => 'per_01HQ3K4N7XYZABC',
                                                                'externalEmployeeId' => 'EMP-00142',
                                                                'employeeName' => 'María García López'
                                ]
                ],
                'source' => 'cadana',
                'filingReference' => '0123456ABCD7890EF'
        ]
    ],
    'countryCode' => '<string>',
    'filingTypeIds' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cadanapay.com/v1/statutory/filings/batch"

	payload := strings.NewReader("{\n  \"businessId\": \"<string>\",\n  \"periodStart\": \"2026-02-01\",\n  \"periodEnd\": \"2026-02-28\",\n  \"payrollRunIds\": [\n    \"<string>\"\n  ],\n  \"filings\": [\n    {\n      \"filingTypeId\": \"ft_mx_isr_monthly\",\n      \"currency\": \"MXN\",\n      \"breakdown\": [\n        {\n          \"amount\": 4250,\n          \"personId\": \"per_01HQ3K4N7XYZABC\",\n          \"externalEmployeeId\": \"EMP-00142\",\n          \"employeeName\": \"María García López\"\n        }\n      ],\n      \"source\": \"cadana\",\n      \"filingReference\": \"0123456ABCD7890EF\"\n    }\n  ],\n  \"countryCode\": \"<string>\",\n  \"filingTypeIds\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cadanapay.com/v1/statutory/filings/batch")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"businessId\": \"<string>\",\n  \"periodStart\": \"2026-02-01\",\n  \"periodEnd\": \"2026-02-28\",\n  \"payrollRunIds\": [\n    \"<string>\"\n  ],\n  \"filings\": [\n    {\n      \"filingTypeId\": \"ft_mx_isr_monthly\",\n      \"currency\": \"MXN\",\n      \"breakdown\": [\n        {\n          \"amount\": 4250,\n          \"personId\": \"per_01HQ3K4N7XYZABC\",\n          \"externalEmployeeId\": \"EMP-00142\",\n          \"employeeName\": \"María García López\"\n        }\n      ],\n      \"source\": \"cadana\",\n      \"filingReference\": \"0123456ABCD7890EF\"\n    }\n  ],\n  \"countryCode\": \"<string>\",\n  \"filingTypeIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cadanapay.com/v1/statutory/filings/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"businessId\": \"<string>\",\n  \"periodStart\": \"2026-02-01\",\n  \"periodEnd\": \"2026-02-28\",\n  \"payrollRunIds\": [\n    \"<string>\"\n  ],\n  \"filings\": [\n    {\n      \"filingTypeId\": \"ft_mx_isr_monthly\",\n      \"currency\": \"MXN\",\n      \"breakdown\": [\n        {\n          \"amount\": 4250,\n          \"personId\": \"per_01HQ3K4N7XYZABC\",\n          \"externalEmployeeId\": \"EMP-00142\",\n          \"employeeName\": \"María García López\"\n        }\n      ],\n      \"source\": \"cadana\",\n      \"filingReference\": \"0123456ABCD7890EF\"\n    }\n  ],\n  \"countryCode\": \"<string>\",\n  \"filingTypeIds\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

201

{
  "data": [
    {
      "id": "fil_01HQ3K4N7XYZABC"
    }
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "countryCode is required",
    "details": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  }
}

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

Batch create filings for a business and period in one call. Pick one input shape:

• payrollRunIds — Cadana derives the filing types and breakdowns from the linked Cadana payroll runs. Each filing is created as source: cadana and runs the full lifecycle.
• filings — Provide an explicit array, each entry with its own filingTypeId, currency, and breakdown. Each entry can be source: cadana (Cadana files for you) or source: external (you already filed and supply a filingReference). Use this when amounts were computed outside Cadana.

Exactly one of payrollRunIds or filings must be provided. All entries in filings must share the same source (all cadana or all external); mixing sources returns 400.

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

Show child attributes

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 payrollRunIds mode). If omitted, creates all applicable filing types based on worker flags.

Response

201

application/json

Filings created

data · object[]

Show child attributes