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

# Template configuration

> Configure import templates with JSON to map CSV or Excel columns to Acclaim entities.

**Import templates** define how your CSV or Excel file is translated into structured data in Acclaim. You configure them with **JSON**. They control how columns map to entity fields, which rows are processed, validation behavior, and default values.

## Template structure

A template includes:

| Field                | Description                                          |
| -------------------- | ---------------------------------------------------- |
| Name                 | Descriptive template name                            |
| Object type          | Entity being imported (Payee, Payout, Payout method) |
| Header row index     | Row containing column headers (0-based)              |
| Data start row index | Row where data begins (0-based)                      |
| Columns              | JSON array of column mappings                        |

## Columns configuration

Each column mapping defines how a file column maps to a field.

### Properties

| Property       | Required | Description                    |
| -------------- | -------- | ------------------------------ |
| `propertyPath` | Yes      | Field to map to                |
| `headerName`   | No       | Column name (case-insensitive) |
| `columnIndex`  | No       | Column position (0-based)      |
| `required`     | No       | Skip row if empty              |
| `defaultValue` | No       | Fallback value                 |

If both `headerName` and `columnIndex` are provided, **`columnIndex` takes precedence**.

## Basic example

```json theme={null}
[
  {
    "propertyPath": "given_name",
    "headerName": "First Name",
    "required": true
  },
  {
    "propertyPath": "family_name",
    "headerName": "Last Name",
    "required": true
  }
]
```

## Using column index

```json theme={null}
[
  {
    "propertyPath": "given_name",
    "columnIndex": 0,
    "required": true
  },
  {
    "propertyPath": "family_name",
    "columnIndex": 1,
    "required": true
  }
]
```

## Default values

```json theme={null}
{
  "propertyPath": "company",
  "headerName": "Company",
  "defaultValue": "Individual"
}
```

## Row configuration

### Header row

Defines where headers are located. Example:

```
headerRowIndex: 0
```

### Data start row

Defines where data begins. Example:

```
dataStartRowIndex: 1
```

## Object types

Each template targets one **object type**: **Payee**, **Payout**, or **Payout method**. That choice controls which `propertyPath` values are valid for column mappings.

## Available parameters

The lists below are generated from `data/importTemplateObjectFields.json` in this repository. Run `npx tsx scripts/generate-import-template-field-docs.ts` after you edit the JSON.

### Payee

Use when the template creates or updates **payee** records. Payout upload rows often use dot paths such as `payee.first_name` instead; see [File format](/guides/disburse/file-uploads/file-format) for that layout.

<ResponseField name={"given_name"} type="string" required={false}>
  Given or first name for the payee when you map a single column to this field.
</ResponseField>

<ResponseField name={"family_name"} type="string" required={false}>
  Family or last name for the payee when you map a single column to this field.
</ResponseField>

<ResponseField name={"email"} type="string" required={false}>
  Email address for the payee, if your import uses it.
</ResponseField>

<ResponseField name={"phone"} type="string" required={false}>
  Phone number for the payee, if your import uses it.
</ResponseField>

<ResponseField name={"company"} type="string" required={false}>
  Company or organization name when the payee is a business, or a default label such as Individual when you use `defaultValue` in the column mapping.
</ResponseField>

### Payout

Use when each row represents a **payout**. Required fields depend on payee type, payout method, and destination; see [File format](/guides/disburse/file-uploads/file-format) and [Validation rules](/guides/disburse/file-uploads/validation).

<ResponseField name={"payee"} type="string" required={false}>
  Identifier or external reference that ties the row to a payee, per your template and environment.
</ResponseField>

<ResponseField name={"treasury_account"} type="string" required={false}>
  Identifier for the treasury account Acclaim should debit when funding this payout.
</ResponseField>

<ResponseField name={"reference"} type="string" required={false}>
  Your reference or memo for reconciliation and support.
</ResponseField>

<ResponseField name={"amount"} type="number" required={false}>
  Payout amount as a numeric value without currency symbols in the cell.
</ResponseField>

<ResponseField name={"currency"} type="string" required={false}>
  ISO 4217 currency code for the payout (for example USD, EUR, MXN).
</ResponseField>

<ResponseField name={"payment_currency"} type="string" required={false}>
  Alternative column name some templates use for the payout currency; align with `currency` if both appear in your file.
</ResponseField>

<ResponseField name={"payout_method"} type="string" required={false}>
  Payout method identifier or selector for the row, when your template separates method choice from bank details.
</ResponseField>

### Payout method

Use when the template maps **bank or rail identifiers** and related attributes. Exact required fields depend on the method and country; use [Supported payout countries](/guides/disburse/countries) for method-specific requirements.

<ResponseField name={"payout_method_type"} type="string" required={false}>
  Method or rail code for the payout (for example values listed on destination country pages).
</ResponseField>

<ResponseField name={"bank_account.account_holder_name"} type="string" required={false}>
  Name on the account for the payout method.
</ResponseField>

<ResponseField name={"bank_account.account_number"} type="string" required={false}>
  Local account number where the rail requires it.
</ResponseField>

<ResponseField name={"bank_account.swift_code"} type="string" required={false}>
  SWIFT or BIC code for international transfers where supported.
</ResponseField>

<ResponseField name={"bank_account.iban"} type="string" required={false}>
  IBAN where the destination rail uses it.
</ResponseField>

<ResponseField name={"bank_account.clabe"} type="string" required={false}>
  18-digit CLABE for Mexico where that rail applies.
</ResponseField>

<ResponseField name={"beneficiary.address.country"} type="string" required={false}>
  Country for the beneficiary when your template or rail requires address context.
</ResponseField>

## Validation behavior

When you process a file against a template, typical outcomes include:

| Situation               | Result                                                          |
| ----------------------- | --------------------------------------------------------------- |
| Missing required fields | Row skipped (or handled per your template rules)                |
| Invalid format          | Row rejected                                                    |
| Mapping errors          | Incorrect or incomplete data—fix the template before large runs |

<Tip>
  Prefer **header names** over raw column indexes when possible so files stay readable if columns shift slightly. Test with a **small file** before bulk uploads.
</Tip>

## Best practices

* Use header names instead of indexes when you can.
* Mark required fields explicitly.
* Test with small files first.
* Use defaults to reduce required columns.

## Related resources

* [File uploads overview](./overview)
* [File format](./file-format)
* [Validation rules](./validation)
* [Processing flow](./processing)
* [Error handling](./errors)