Integration Guide

Prerequisites

API key from Dashboard

Get your API key from the Cadana Dashboard. See Authentication for details.

Active business on Cadana

Your business must be created and verified on the platform.

Check Location Support

Verify which countries and regions are supported. The response includes valid state/region codes needed when creating a person. Response:

{
  "data": [
    {
      "name": "Australia",
      "code": "AU",
      "regions": [
        { "name": "New South Wales", "code": "NSW" },
        { "name": "Victoria", "code": "VIC" },
        { "name": "Queensland", "code": "QLD" }
      ]
    }
  ]
}

Get Required Tax Fields

Some countries require additional fields (marital status, number of dependents, etc.) for accurate calculations. Retrieve the required fields before creating a person. Response:

{
  "data": [
    {
      "name": "maritalStatus",
      "required": true,
      "type": "string",
      "enum": ["single", "married", "divorced", "widowed"],
      "description": "Marital status for tax deduction eligibility"
    },
    {
      "name": "numberOfDependents",
      "required": false,
      "type": "number",
      "description": "Number of dependents for tax relief",
      "default": 0
    },
    {
      "name": "isResident",
      "required": false,
      "type": "boolean",
      "description": "Whether the worker is a tax resident",
      "default": true
    }
  ],
  "schemaVersion": "2020-12",
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "additionalProperties": false,
    "required": ["maritalStatus"],
    "properties": {
      "maritalStatus": { "type": "string", "enum": ["single", "married", "divorced", "widowed"] },
      "numberOfDependents": { "type": "number", "minimum": 0, "default": 0 },
      "isResident": { "type": "boolean", "default": true }
    }
  }
}

Field properties

Each field is self-describing, so you can render an onboarding form dynamically instead of hard-coding one per country.

Property	Description
`name`	Field key. Submit the collected value under this key in `additionalAttributes` on `POST /v1/tax/calculate` or in the person’s `taxProfile`.
`description`	Human-readable explanation — use it as the form label or helper text.
`type`	Value type: `string`, `number`, or `boolean`. Maps to the input control (text, number, checkbox).
`required`	Whether the field must be provided. Required fields never rely on a default.
`enum`	Present when the field accepts a fixed set of values — render as a dropdown of these options.
`default`	Present when the field has a default. If you omit the field, the engine applies this value automatically — so you can pre-fill the control with it, and optional fields that have a `default` need no user input at all.

The default is the same value the engine seeds during calculation, so what you see here is exactly what’s applied when the field is omitted. Pre-populate your form with each field’s default to reduce the inputs a worker has to fill in.

Rendering forms from the schema

Alongside data, the response carries a full JSON Schema (draft 2020-12) under schema, and the schemaVersion it targets. data is enough for a flat form; schema describes the same fields and the relationships between them, so you can render conditional fields and validate a completed profile with any standard validator (e.g. Ajv for JavaScript or jsonschema for Python) — no per-country logic.

Keyword	What it tells you
`properties`	Available fields with their types and constraints
`enum`	Allowed values for a fixed-option field — render as a dropdown
`const`	A fixed value the field must take (used inside conditional rules)
`minimum`	Lower bound for a numeric field
`default`	Value the engine applies when the field is omitted — use it to pre-fill
`required`	Fields that must be present
`additionalProperties`	Always `false` — only listed fields are accepted
`allOf` / `if`-`then`	Conditional rules — e.g. if one field has a given value, another is constrained

Some cross-field relationships have no standard keyword, so they are expressed as x-cadana-* extensions. A standard validator ignores them; handle them yourself where you need the rule enforced:

Keyword	Meaning
`x-cadana-lteField`	This numeric field must be ≤ the named field (e.g. `childrenUnder3 ≤ numberOfChildren`)
`x-cadana-groupSumLteField`	The sum of every field sharing a group must be ≤ the named field
`x-cadana-group`	The group label a field belongs to (used with `x-cadana-groupSumLteField`)
`x-cadana-ui`	Rendering hints keyed by field — e.g. `visibleWhen` tells your form when to show a conditional field
`x-cadana-provider`	Internal source that surfaces the field. May be omitted

For example, a country schema can gate one field on another and cap a subset against a total:

{
  "properties": {
    "numberOfChildren": { "type": "number", "minimum": 0, "default": 0 },
    "childrenUnder3": { "type": "number", "minimum": 0, "default": 0, "x-cadana-lteField": "numberOfChildren" },
    "disabilityDegree": { "type": "string", "enum": ["none", "33_to_64", "65_plus"], "default": "none" },
    "hasReducedMobility": { "type": "boolean", "default": false }
  },
  "allOf": [
    {
      "if": { "not": { "required": ["disabilityDegree"], "properties": { "disabilityDegree": { "const": "33_to_64" } } } },
      "then": { "properties": { "hasReducedMobility": { "const": false } } }
    }
  ],
  "x-cadana-ui": {
    "hasReducedMobility": { "visibleWhen": { "field": "disabilityDegree", "equals": "33_to_64" } }
  }
}

Read x-cadana-ui.visibleWhen to decide when to show hasReducedMobility, and let the schema be the source of truth for validation before you submit.

Create a Person

Create a person with their address, salary, and compensation details. The returned id is used for all subsequent tax calculations. Response:

{
  "id": "81933bed-97ba-4477-81a7-b8c5ab507b6f"
}

Populate any country-specific fields from the previous step on the person record. Use PUT /v1/persons/{id}/personalInfo to add taxId and socialSecurityId, or PUT /v1/persons/{id}/taxProfile for taxProfile fields like marital status and number of dependents.

Manage Persons

Operation	Endpoint
Get	`GET /v1/persons/{id}`
Update basic info	`PUT /v1/persons/{id}/basicInfo`
Update personal info	`PUT /v1/persons/{id}/personalInfo`
Update job info	`PUT /v1/persons/{id}/jobInfo`
Update tax profile	`PUT /v1/persons/{id}/taxProfile`

Calculate Taxes

Calculate taxes for a person. Pass the personId and the salary for the period. Response:

{
  "personId": "81933bed-97ba-4477-81a7-b8c5ab507b6f",
  "grossAmount": { "amount": 4000000, "currency": "MXN" },
  "netAmount": { "amount": 3050000, "currency": "MXN" },
  "deductions": [
    {
      "name": "ISR (Impuesto Sobre la Renta)",
      "isStatutory": true,
      "amount": { "amount": 680000, "currency": "MXN" }
    },
    {
      "name": "IMSS Employee Contribution",
      "isStatutory": true,
      "amount": { "amount": 270000, "currency": "MXN" }
    }
  ],
  "employerContributions": [
    {
      "name": "IMSS Employer Contribution",
      "isStatutory": true,
      "amount": { "amount": 840000, "currency": "MXN" }
    },
    {
      "name": "INFONAVIT (5%)",
      "isStatutory": true,
      "amount": { "amount": 200000, "currency": "MXN" }
    }
  ]
}

Response fields

Field	Description
`grossAmount`	Input salary for the period
`netAmount`	Take-home pay after all deductions
`allowances`	Imputed-income line items (e.g. benefits-in-kind) surfaced by the country engine. Omitted when none apply.
`deductions`	Employee deductions (social security, income tax, etc.). Each entry’s `isStatutory` flag indicates whether the deduction is mandated by law.
`employerContributions`	Employer-side costs not deducted from the employee’s pay.
`summary`	Step-by-step calculation breakdown showing formulas, brackets, and rates for each line item

The additionalAttributes field accepts country-specific values like year-to-date salary or pension contributions. These are calculation-time inputs — different from the tax profile fields set when creating a person. Use the tax fields endpoint to discover what’s available for each country. Numeric fields are expressed in major currency units — e.g. India’s hraReceived, rentPaid, and declared80c are whole rupees — unlike amount objects, which use the lowest denomination.

Next Steps

Employment Cost Calculator

Quick estimates without a person record — great for compensation planning

Tax API Reference

Full API documentation

Global Tax Engine

Product overview and capabilities

File Statutory Returns

After calculating taxes, file returns and remit to government authorities

Run Payroll

Pay your workers using the calculated tax amounts

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

Prerequisites

Check Location Support

Get Required Tax Fields

Field properties

Rendering forms from the schema

Create a Person

Manage Persons

Calculate Taxes

Response fields

Next Steps

Employment Cost Calculator

Tax API Reference

Global Tax Engine

File Statutory Returns

Run Payroll

​Prerequisites

​Check Location Support

​Get Required Tax Fields

​Field properties

​Rendering forms from the schema

​Create a Person

​Manage Persons

​Calculate Taxes

​Response fields

​Next Steps

Employment Cost Calculator

Tax API Reference

Global Tax Engine

File Statutory Returns

Run Payroll

Prerequisites

Check Location Support

Get Required Tax Fields

Field properties

Rendering forms from the schema

Create a Person

Manage Persons

Calculate Taxes

Response fields

Next Steps