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

# Batch call recipient file: columns and format

> Reference for the CSV or Excel file you upload to a batch call: required and optional columns, phone number rules, variables, time zones and validation.

The recipient file is the list a [batch call](https://docs.tryhamsa.com/agents/connect/batch-calls.md) works through: one row per person, with their phone number and any details the agent should use on that call. This page lists the columns Hamsa reads, the phone number rules, and how to fix rows that don't pass.

## File format

* `.csv` or `.xlsx` (Excel). Older `.xls` files aren't accepted. From an Excel file, only the first sheet is read.
* The first row holds the column names. Every row after it is one recipient.
* Empty lines are skipped.
* Save CSV files as UTF-8 so Arabic and other non-Latin text comes through. The CSV template already is.

Start from a template: in the batch call form, click **Download Excel template** or **Download CSV template**. Both have these columns and one sample row:

```csv theme={null}
phone_number,name,ignore_e164_validation,dynamic_variable1,dynamic_variable2
+12025551234,John Doe,false,value1,value2
```

Replace `dynamic_variable1` and `dynamic_variable2` with your own column names.

## Columns

| Column | Required | What it does |
| - | - | - |
| `phone_number` | Yes | The number to call. `phoneNumber` also works. See [Phone number rules](#phone-number-rules). |
| `name` | No | Shown in the recipients table, and passed to the agent as `{{name}}`. |
| `ignore_e164_validation` | No | `true` lets a local number without a country code through. Anything else counts as `false`. `ignoreE164Validation` also works. |
| `timezone` | No | The recipient's IANA time zone, for example `Asia/Riyadh`. The calling window is applied in this time zone for this recipient. See [Time zones](#time-zones). |
| Any other column | No | Becomes a variable for that recipient's call, named exactly like the column. |

### Columns become variables

Every column that isn't `phone_number` or `ignore_e164_validation` becomes a variable the agent can use, `name` included. A column named `plan` is `{{plan}}` in the prompt or greeting:

```csv theme={null}
phone_number,name,renewal_date,plan
+971501234567,Sara,15 November,Gold
+971509876543,Omar,20 November,Silver
```

```text theme={null}
Hello {{name}}, I'm calling about your {{plan}} plan, which renews on {{renewal_date}}.
```

* Names are used exactly as written, including case and spaces. `Customer Name` and `customer_name` are different variables. Use letters, numbers and underscores to keep them easy to write in prompts.
* An empty cell isn't sent at all. If the agent uses that variable, it's empty on that call, and the call goes on.
* Values arrive as text. See [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md) to compare or format them.
* If the agent's prod [environment](https://docs.tryhamsa.com/agents/variables/environment-variables.md) has a variable with the same name, the environment value wins over the column.

See [Pass values when a call starts](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md) for more on variables.

## Phone number rules

| Rule | Example that passes | Error when it doesn't |
| - | - | - |
| Digits only, with an optional leading `+` or `00`. No spaces, dashes or brackets. | `+14155552671` | "Phone number can only contain digits with an optional + or 00 prefix (no spaces, dashes, or special characters)" |
| With `+` or `00`, it must be a valid international number. | `0014155552671` | "Invalid phone number", followed by a hint to check the country code and format |
| Without a prefix, it's refused unless `ignore_e164_validation` is `true`. | | "Phone number must start with + and a country code (e.g. +1, +44)" |
| A local number with `ignore_e164_validation` set to `true` can have up to 13 digits. | `6505551234` | "Invalid phone number, local phone number must not exceed 13 digits" |
| Each number appears once in the file. | | "Duplicate phone number found in recipients list" |

A number with `00` is saved with `+` instead.

In Excel, format the phone number column as text so Excel keeps the leading `+`. The Excel template already does.

> [!NOTE]
>
> A number without a prefix is dialed with a `+` in front of it. A number with `ignore_e164_validation` set to `true` is dialed exactly as written, with no `+` added. Whether a local number connects depends on the phone number you call from, so use full international numbers when you can.

## Time zones

The calling window you set on the batch call (**Time range** and **Days of week**) is read in the batch call's **Timezone**. Add a `timezone` column to call each recipient inside the window in their own time zone, for example when one list covers Riyadh and Cairo.

* Use IANA names such as `Asia/Riyadh`, `Africa/Cairo` or `Europe/London`. Abbreviations like `GST` aren't IANA names.
* A time zone Hamsa doesn't recognize is reported when you upload the file, so you can fix that row.

## Fix rejected rows

After you upload, **Upload validation results** shows **Accepted** and **Rejected** rows.

![Upload validation results with 21 accepted and 2 rejected rows](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-upload-validation-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=1522fa3763b82269dee92adcfc144dd9)

**1. Open the Rejected tab**

Each row shows why it was rejected.

![The Rejected tab: row 21 with a number written with spaces and no country code, and row 22 with an invalid number, each with Edit](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-rejected-rows-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=7154b7679330323070ceebda04defd97)

**2. Click Edit**

The row opens as **Fixing row #n**. Change the phone number, the name, **ignore e164 validation**, or any variable value. Column names can't change here.

**3. Click Add to accepted**

Once the row is valid, the dialog says so and **Add to accepted** moves it over.

![Fixing row #21: the corrected phone number, the name, ignore e164 validation, the row's variables, and the row is now valid with Add to accepted](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-fix-row-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=9d4ef0d46cf0d9c4fe65eaf52c0d34f5)

**4. Click Add accepted rows**

Accepted and fixed rows are added. Rows still rejected are dropped.

After adding, **View recipients** lets you review the list and remove rows. **Upload another file** replaces the whole list: it asks **Replace existing recipients?** first.

## Limits

| Limit | Value |
| - | - |
| Recipients per batch call | At least 1. No fixed maximum. |
| File size | The upload area says "Up to 50 MB". |
| Local number length | 13 digits |

## Related

> [card] [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md)
>
> Create, schedule and follow a batch call.

> [card] [Pass values when a call starts](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md)
>
> How column values reach your prompt.

> [card] [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md)
>
> Format and compare values in prompts.

> [card] [Environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md)
>
> Values that apply to every call in an environment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.