Get a filing

Beta — contact Cadana to enable access for your business.

Returns full filing details including amounts, status history, blocked reasons, and linked payroll runs.

GET /v1/statutory/filings/{filing_id}

Get a filing

cURL

curl --request GET \
  --url https://api.cadanapay.com/v1/statutory/filings/{filing_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cadanapay.com/v1/statutory/filings/{filing_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cadanapay.com/v1/statutory/filings/{filing_id}', 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/{filing_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.cadanapay.com/v1/statutory/filings/{filing_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cadanapay.com/v1/statutory/filings/{filing_id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

200

{
  "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
    }
  ],
  "amendedBy": "<string>",
  "amendsFilingId": "<string>",
  "createdAt": 1709280000,
  "updatedAt": 1709280000
}

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

Path Parameters

filing_id · string · required

Filing identifier

Response

200

application/json

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

Show child attributes

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.

Show child attributes

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.

Show child attributes

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

Show child attributes

amendedBy · string

ID of the amendment filing that supersedes this one. Present only after the filing has been amended; the filing itself stays accepted.

amendsFilingId · string

ID of the original filing this amendment corrects. Present only on amendment filings created via the amend endpoint.

createdAt · number<epoch>

Unix epoch timestamp

Example:

1709280000

updatedAt · number<epoch>

Unix epoch timestamp

Example:

1709280000