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 /v1/statutory/jurisdictions/{country_code}/required-fields

Get required fields for tax calculation and statutory filing

cURL

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

200

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

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"