Integration Guide

Integrate the Global Tax Engine API

Prerequisites

1. API key from Dashboard

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

2. 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
    }
  ]
}

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.

---

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": "per_01ABC..."
}

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": "per_01ABC...",
  "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
outputCurrency, fxRate	Present only when the request passed outputCurrency — echoes the requested currency and the rate applied.

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.

---

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