Skip to main content
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:
FieldDescription
NameDescriptive template name
Object typeEntity being imported (Payee, Payout, Payout method)
Header row indexRow containing column headers (0-based)
Data start row indexRow where data begins (0-based)
ColumnsJSON array of column mappings

​
Columns configuration

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

​
Properties

PropertyRequiredDescription
propertyPathYesField to map to
headerNameNoColumn name (case-insensitive)
columnIndexNoColumn position (0-based)
requiredNoSkip row if empty
defaultValueNoFallback 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.
​
given_name
string
Given or first name for the payee when you map a single column to this field.
​
family_name
string
Family or last name for the payee when you map a single column to this field.
​
email
string
Email address for the payee, if your import uses it.
​
phone
string
Phone number for the payee, if your import uses it.
​
company
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.
​
payee
string
Identifier or external reference that ties the row to a payee, per your template and environment.
​
treasury_account
string
Identifier for the treasury account Acclaim should debit when funding this payout.
​
reference
string
Your reference or memo for reconciliation and support.
​
amount
number
Payout amount as a numeric value without currency symbols in the cell.
​
currency
string
ISO 4217 currency code for the payout (for example USD, EUR, MXN).
​
payment_currency
string
Alternative column name some templates use for the payout currency; align with currency if both appear in your file.
​
payout_method
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.
​
payout_method_type
string
Method or rail code for the payout (for example values listed on destination country pages).
​
bank_account.account_holder_name
string
Name on the account for the payout method.
​
bank_account.account_number
string
Local account number where the rail requires it.
​
bank_account.swift_code
string
SWIFT or BIC code for international transfers where supported.
​
bank_account.iban
string
IBAN where the destination rail uses it.
​
bank_account.clabe
string
18-digit CLABE for Mexico where that rail applies.
​
beneficiary.address.country
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:
SituationResult
Missing required fieldsRow skipped (or handled per your template rules)
Invalid formatRow rejected
Mapping errorsIncorrect 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.
Last modified on March 29, 2026