Get required fields for tax calculation and statutory filing

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

{
  "countryCode": "MX",
  "version": 3,
  "fields": [
    {
      "key": "taxId",
      "name": "RFC (Registro Federal de Contribuyentes)",
      "description": "SAT-issued RFC, required on all ISR withholding returns",
      "type": "string",
      "required": true,
      "entity": "person",
      "scope": [
        "calculation",
        "filing"
      ],
      "enum": [
        "<string>"
      ],
      "pattern": "^[A-Z&Ñ]{4}\\d{6}[A-Z0-9]{3}$",
      "condition": {
        "field": "is_pensionable",
        "equals": true
      }
    }
  ],
  "workerType": "employee"
}

Jurisdictions

Get required fields for tax calculation and statutory filing

Returns all fields required for tax calculation and/or statutory filing in this jurisdiction. This is a discovery endpoint — it tells you what data needs to be collected for both persons (workers) and businesses (employers).

Each field includes:

entity — Who the field belongs to: person (worker data) or business (employer data)
scope — Whether the field is needed for calculation (tax engine input), filing (statutory return), or both
condition — When present, the field only applies if another field matches a specific value (e.g. pension PIN only when is_pensionable is true)

Use this to:

Render onboarding forms with the right fields for each country
Filter by entity to build separate person vs. business forms
Validate that existing records have complete data
Understand what worker_data requirements will surface if fields are missing

How to submit fields by scope:

scope: ["filing"] fields → Submit via PUT /v1/statutory/persons/{id}/fields/{countryCode} (person entity) or PUT /v1/statutory/businesses/{id}/fields/{countryCode} (business entity)
scope: ["calculation"] fields → Submit via PUT /v1/persons/{id}/taxProfile
scope: ["filing", "calculation"] fields → Submit to both endpoints

GET

statutory

jurisdictions

{country_code}

required-fields

Get required fields for tax calculation and statutory filing

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

{
  "countryCode": "MX",
  "version": 3,
  "fields": [
    {
      "key": "taxId",
      "name": "RFC (Registro Federal de Contribuyentes)",
      "description": "SAT-issued RFC, required on all ISR withholding returns",
      "type": "string",
      "required": true,
      "entity": "person",
      "scope": [
        "calculation",
        "filing"
      ],
      "enum": [
        "<string>"
      ],
      "pattern": "^[A-Z&Ñ]{4}\\d{6}[A-Z0-9]{3}$",
      "condition": {
        "field": "is_pensionable",
        "equals": true
      }
    }
  ],
  "workerType": "employee"
}

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

country_code

string

required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Z]{2}$

Query Parameters

worker_type

enum<string>

Filter fields by worker type

Available options:

employee,

contractor

scope

enum<string>

Filter fields by scope — "calculation" for tax engine inputs, "filing" for statutory return fields. Omit to return all fields.

Available options:

calculation,

filing

Response

200 - application/json

Required fields with entity, scope, type, and validation rules

Flat list of fields required for tax calculation and/or statutory filing in a jurisdiction. Each field includes its entity (person or business), scope (calculation, filing, or both), and validation rules.

Fields with entity: "person" are worker-level data. Fields with entity: "business" are employer-level data. Use the entity field to build separate onboarding forms for workers and employers.

countryCode

string

required

Example:

"MX"

version

integer

required

Schema version number, per jurisdiction. Increments when fields are added, removed, or changed for this country. Use this to detect when your cached field list is stale.

Example:

3

fields

object[]

required

Show child attributes

workerType

enum<string>

Available options:

employee,

contractor

Example:

"employee"

List filing types for a jurisdiction

List filings

⌘I