Skip to main content
GET
/
v1
/
statutory
/
filings
/
{filing_id}
Get a filing
curl --request GET \
  --url https://api.cadanapay.com/v1/statutory/filings/{filing_id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "fil_01HQ3K4N7XYZABC",
  "businessId": "biz_01HQ3K4N7XYZABC",
  "countryCode": "MX",
  "source": "cadana",
  "filingTypeId": "ft_mx_isr_monthly",
  "filingTypeName": "ISR Withholding",
  "authorityId": "auth_mx_sat",
  "authorityName": "SAT",
  "filingReference": "0123456ABCD7890EF",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-31",
    "label": "January 2026"
  },
  "dueAt": "2026-02-10",
  "amounts": {
    "currency": "MXN",
    "total": 82345
  },
  "workerCount": 15,
  "payrollRunIds": [
    "<string>"
  ],
  "breakdown": [
    {
      "amount": 4250,
      "personId": "per_01HQ3K4N7XYZABC",
      "externalEmployeeId": "EMP-00142",
      "employeeName": "María García López"
    }
  ],
  "blockedReasons": [
    "Missing worker RFC for per_01ABC",
    "Business IMSS registration not found"
  ],
  "statusHistory": [
    {
      "from": "pending",
      "to": "in_review",
      "timestamp": 1709654400
    }
  ],
  "createdAt": 1709280000,
  "updatedAt": 1709280000
}

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.

Path Parameters

​
filing_id
string
required

Filing identifier

Response

Filing details

Full filing detail returned by GET /v1/statutory/filings/{id}. Includes amounts, status history, and linked payroll runs.

​
id
string
Example:

"fil_01HQ3K4N7XYZABC"

​
businessId
string
Example:

"biz_01HQ3K4N7XYZABC"

​
countryCode
string
Example:

"MX"

​
source
enum<string>

How the filing data was sourced.

  • cadana — Cadana prepared and submitted the return to the authority. The filing runs the full lifecycle (pending → in_review → approved → submitted → accepted).
  • external — You filed the return with the authority yourself and submitted the resulting totals + filingReference to Cadana so a remittance can be created against it. External filings are created directly in accepted and do not run the submission lifecycle.
Available options:
cadana,
external
Example:

"cadana"

​
filingTypeId
string

Filing type identifier (from jurisdiction filing types)

Example:

"ft_mx_isr_monthly"

​
filingTypeName
string

Human-readable filing type name

Example:

"ISR Withholding"

​
authorityId
string

Government authority identifier

Example:

"auth_mx_sat"

​
authorityName
string

Government authority name

Example:

"SAT"

​
filingReference
string | null

Government-issued reference for this filing. The exact term varies by country: Línea de Captura in Mexico, acuse de recibo for some SAT receipts, challan number in India, BRN in Nigeria, NPC in some others.

For source: external filings this is required at creation time — it's what the receiving bank or authority uses to attribute the remittance payment to the filing. For source: cadana filings Cadana populates this once the authority confirms receipt.

Example:

"0123456ABCD7890EF"

​
status
enum<string>

Filing lifecycle for source: cadana: pending → in_review → approved → submitted → accepted. Filings can become blocked at pending or in_review if data is missing, and return to pending once resolved. Rejected filings return to pending for correction. Any pre-submit state can be cancelled.

For source: external filings, the filing is created directly in accepted and stays there — there is no submission step for Cadana to run because you already filed with the authority.

Available options:
pending,
blocked,
in_review,
approved,
submitted,
accepted,
rejected,
cancelled
​
period
object
​
dueAt
string

Deadline for submission to the authority

Example:

"2026-02-10"

​
amounts
object

Derived totals for the filing. Read-only on responses — Cadana computes these values from the breakdown lines. You do not pass amounts when creating a filing; provide the breakdown array and the total falls out automatically.

​
workerCount
integer

Number of distinct workers in the filing's breakdown (counted via personId or externalEmployeeId). Zero for purely business-level filings.

Example:

15

​
payrollRunIds
string[]

Linked Cadana payroll runs (when populated via a payroll-run shortcut)

​
breakdown
object[]

Per-employee contribution lines that roll up into the filing total. For source: cadana filings Cadana populates this from payroll; for source: external you provide it at creation time.

​
blockedReasons
string[]

Human-readable reasons why this filing is blocked. Present when status is blocked. Reasons auto-clear when the underlying data is submitted.

Example:
[
  "Missing worker RFC for per_01ABC",
  "Business IMSS registration not found"
]
​
statusHistory
object[]
​
createdAt
number<epoch>

Unix epoch timestamp

Example:

1709280000

​
updatedAt
number<epoch>

Unix epoch timestamp

Example:

1709280000