Template configuration

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

[
  {
    "propertyPath": "given_name",
    "headerName": "First Name",
    "required": true
  },
  {
    "propertyPath": "family_name",
    "headerName": "Last Name",
    "required": true
  }
]

Using column index

[
  {
    "propertyPath": "given_name",
    "columnIndex": 0,
    "required": true
  },
  {
    "propertyPath": "family_name",
    "columnIndex": 1,
    "required": true
  }
]

Default values

{
  "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 for that layout.

string

Given or first name for the payee when you map a single column to this field.

string

Family or last name for the payee when you map a single column to this field.

string

Email address for the payee, if your import uses it.

string

Phone number for the payee, if your import uses it.

string

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.

Payout

Use when each row represents a payout. Required fields depend on payee type, payout method, and destination; see File format and Validation rules.

string

Identifier or external reference that ties the row to a payee, per your template and environment.

string

Identifier for the treasury account Acclaim should debit when funding this payout.

string

Your reference or memo for reconciliation and support.

number

Payout amount as a numeric value without currency symbols in the cell.

string

ISO 4217 currency code for the payout (for example USD, EUR, MXN).

string

Alternative column name some templates use for the payout currency; align with currency if both appear in your file.

string

Payout method identifier or selector for the row, when your template separates method choice from bank details.

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 for method-specific requirements.

string

Method or rail code for the payout (for example values listed on destination country pages).

string

Name on the account for the payout method.

string

Local account number where the rail requires it.

string

SWIFT or BIC code for international transfers where supported.

string

IBAN where the destination rail uses it.

string

18-digit CLABE for Mexico where that rail applies.

string

Country for the beneficiary when your template or rail requires address context.

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

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.

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.

Getting Started

COLLECT

DISBURSE

TREASURY

Platform

Template configuration

Template structure

Columns configuration

Properties

Basic example

Using column index

Default values

Row configuration

Header row

Data start row

Object types

Available parameters

Payee

Payout

Payout method

Validation behavior

Best practices

​Template structure

​Columns configuration

​Properties

​Basic example

​Using column index

​Default values

​Row configuration

​Header row

​Data start row

​Object types

​Available parameters

​Payee

​Payout

​Payout method

​Validation behavior

​Best practices

​Related resources

Template structure

Columns configuration

Properties

Basic example

Using column index

Default values

Row configuration

Header row

Data start row

Object types

Available parameters

Payee

Payout

Payout method

Validation behavior

Best practices

Related resources