> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Guide

> Integrate the Global Tax Engine API

export const ApiExample = ({method = "GET", path, params, body, reference, tenantKey}) => {
  const baseUrl = "https://api.cadanapay.com";
  const query = params ? "?" + Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&") : "";
  const url = `${baseUrl}${path}${query}`;
  const isPlatformPath = (/^\/(v1\/)?platform(\/|$)/).test(path || "");
  const includeTenantKey = tenantKey === undefined ? !isPlatformPath : tenantKey;
  let curl = `curl -X ${method} '${url}' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'`;
  if (includeTenantKey) {
    curl += ` \\\n  -H 'X-MultiTenantKey: YOUR_BUSINESS_TENANT_KEY'`;
  }
  if (body) {
    const formatted = JSON.stringify(body, null, 2);
    curl += ` \\\n  -H 'Content-Type: application/json' \\\n  -d '${formatted}'`;
  }
  return <div>
      <CodeBlock language="bash" filename="bash" wrap>
        {curl}
      </CodeBlock>
      {reference && <div style={{
    marginTop: "-0.5rem",
    marginBottom: "1rem"
  }}>
          <a href={reference} style={{
    fontSize: "0.875rem"
  }}>
            Try it in the playground →
          </a>
        </div>}
    </div>;
};

## Prerequisites

<Steps>
  <Step title="API key from Dashboard">
    Get your API key from the [Cadana Dashboard](https://app.cadanapay.com). See [Authentication](/authentication) for details.
  </Step>

  <Step title="Active business on Cadana">
    Your business must be created and verified on the platform.
  </Step>
</Steps>

***

## Check Location Support

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

<ApiExample method="GET" path="/v1/tax/locations" params={{ country: "AU" }} reference="/api-reference/tax/tax-calculator/list-countries-and-regions" />

**Response:**

```json theme={null}
{
  "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.

<ApiExample method="GET" path="/v1/tax/fields" params={{ country: "MX" }} reference="/api-reference/tax/tax-calculator/list-required-additional-tax-fields-by-country" />

**Response:**

```json theme={null}
{
  "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`](/api-reference/tax/tax-calculator/calculate-taxes) 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. |

<Tip>
  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.
</Tip>

***

## Create a Person

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

<ApiExample method="POST" path="/v1/persons" body={{ type: "EMPLOYEE", firstName: "María", lastName: "García", email: "maria@example.com", phoneNumber: { countryCode: "52", number: "5512345678" }, address: { line1: "Av. Reforma 222", city: "Mexico City", state: "CMX", postalCode: "06600", countryCode: "MX" }, compInfo: { type: "salaried", salary: { amount: 4000000, currency: "MXN" }, frequency: "monthly" } }} reference="/api-reference/workforce/persons/create" />

**Response:**

```json theme={null}
{
  "id": "81933bed-97ba-4477-81a7-b8c5ab507b6f"
}
```

<Tip>
  Populate any country-specific fields from the previous step on the person record. Use [`PUT /v1/persons/{id}/personalInfo`](/api-reference/workforce/persons/update-personal-information) to add `taxId` and `socialSecurityId`, or [`PUT /v1/persons/{id}/taxProfile`](/api-reference/workforce/persons/update-tax-profile) for `taxProfile` fields like marital status and number of dependents.
</Tip>

### Manage Persons

| Operation            | Endpoint                                                                                            |
| :------------------- | :-------------------------------------------------------------------------------------------------- |
| Get                  | [`GET /v1/persons/{id}`](/api-reference/workforce/persons/get)                                      |
| Update basic info    | [`PUT /v1/persons/{id}/basicInfo`](/api-reference/workforce/persons/update-basic-information)       |
| Update personal info | [`PUT /v1/persons/{id}/personalInfo`](/api-reference/workforce/persons/update-personal-information) |
| Update job info      | [`PUT /v1/persons/{id}/jobInfo`](/api-reference/workforce/persons/update-job-information)           |
| Update tax profile   | [`PUT /v1/persons/{id}/taxProfile`](/api-reference/workforce/persons/update-tax-profile)            |

***

## Calculate Taxes

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

<ApiExample method="POST" path="/v1/tax/calculate" body={{ personId: "81933bed-97ba-4477-81a7-b8c5ab507b6f", salary: { amount: 4000000, currency: "MXN" }, additionalAttributes: { ytdSalary: 4000000 } }} reference="/api-reference/tax/tax-calculator/calculate-taxes" />

**Response:**

```json theme={null}
{
  "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](#create-a-person). Use the [tax fields endpoint](#get-required-tax-fields) 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

<CardGroup cols={2}>
  <Card title="Employment Cost Calculator" icon="calculator" href="/tax/estimate">
    Quick estimates without a person record — great for compensation planning
  </Card>

  <Card title="Tax API Reference" icon="code" href="/api-reference/tax">
    Full API documentation
  </Card>

  <Card title="Global Tax Engine" icon="microchip" href="/tax/overview">
    Product overview and capabilities
  </Card>

  <Card title="File Statutory Returns" icon="file-circle-check" href="/statutory/the-full-loop">
    After calculating taxes, file returns and remit to government authorities
  </Card>

  <Card title="Run Payroll" icon="rocket" href="/workforce/pay-workers-via-payroll">
    Pay your workers using the calculated tax amounts
  </Card>
</CardGroup>