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

# Send SMS Batch

> Send SMS messages to a large list of recipients from a pre-uploaded CSV file. Processing is handled asynchronously via a background workflow.

> [!NOTE]
>
> **Enterprise Feature** - SMS batch sending is only available on Enterprise plans. Contact your Bland representative for access.

### Before You Begin: Upload Your CSV

Before calling this endpoint, you must upload your recipient CSV file and get a `file_id`.

Upload your CSV via `POST https://api.bland.ai/v1/files/attach` with `file_type: "batches"`. The response will include a `file_id` (UUID) that you pass to this endpoint.

**CSV format requirements:**

* Must include a column named exactly **`phone_number`** containing E.164-formatted numbers (e.g. `+14155551234`). Numbers without a leading `+` are automatically prefixed.
* The `phone_number` column **cannot be remapped** via `column_mapping` — the column must be named `phone_number` in the CSV itself.
* Additional columns become dynamic variables available in your pathway via `{{column_name}}` syntax.
* Columns named `request_data.fieldname` (dot notation) are automatically parsed into the recipient's `request_data` object.
* JSON arrays of objects are also accepted as an alternative to CSV.

Example CSV:

```csv theme={null}
phone_number,first_name,request_data.account_id
+14155551234,Alice,acc_001
+10987654321,Bob,acc_002
```

***

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Body Parameters

**file\_id** `string` *required*

The ID of a previously uploaded CSV file containing recipient phone numbers. The file must have been uploaded with `file_type: "batches"`. See [Before You Begin](#before-you-begin-upload-your-csv) above.

**global** `object` *required*

Default SMS parameters applied to every message in the batch.

**global object**

**agent\_number** `string` *required*

The E.164 formatted phone number to send messages from. Must be an SMS-enabled inbound number configured on your account.

**agent\_message** `string`

The initial outbound message to send to each recipient. If omitted, the pathway configured on the number will handle the opening message.

**request\_data** `object`

Default request data to associate with each conversation. Per-recipient `request_data` from the CSV is merged on top of this, with recipient values taking precedence.

**metadata** `object`

Custom metadata to attach to each conversation. Returned in all webhook payloads for correlating conversations with your internal systems.

**disposition\_ids** `string[]`

An array of outcome IDs to run when each conversation ends. If omitted, the outcomes configured on the SMS number are used. See [Outcomes](https://docs.bland.ai/tutorials/outcomes.md).

**citation\_schema\_ids** `string[]`

An array of citation schema IDs to extract when each conversation ends. If omitted, the citation schemas configured on the SMS number are used. See [Citations](https://docs.bland.ai/enterprise-features/citations.md).

**column\_mapping** `object`

Maps column names in your CSV to SMS send parameter names. Use this when your CSV column names don't match the expected field names.

Use this to map non-phone columns to `request_data` or other SMS parameters. **Note:** `phone_number` cannot be used as a target — the phone number column in your CSV must be named `phone_number` exactly.

Map columns to `request_data` to make them available as pathway variables:

```json theme={null}
{
  "customer_name": "request_data",
  "preferred_lang": "request_data"
}
```

Only `request_data` is supported as a target — per-recipient fields like `pathway_id` or `persona_id` cannot be overridden from the CSV. Alternatively, use dot notation column names in your CSV directly (e.g. `request_data.customer_name`) to avoid needing `column_mapping` at all.

### Response

**data** `object`

Confirmation that the batch was accepted for processing.

**data object**

**message** `string`

Confirmation message indicating the batch was queued.

**batch\_id** `string`

The `file_id` used for this batch, for reference.

**workflow\_id** `string`

The ID of the background workflow processing this batch.

**errors** `null|array`

`null` on success, or a list of error objects if the request failed.

```json Request theme={null}
{
  "file_id": "file_abc123",
  "global": {
    "agent_number": "+14155551234",
    "pathway_id": "pathway_xyz789",
    "channel": "sms"
  },
  "column_mapping": {
    "customer_name": "request_data"
  }
}
```

```json Response (Success) theme={null}
{
  "data": {
    "message": "SMS batch processing initiated via Temporal workflow",
    "batch_id": "file_abc123",
    "workflow_id": "workflow_def456"
  },
  "errors": null
}
```

```json Error Response (Missing file_id) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "MISSING_FILE_ID",
      "message": "file_id is required"
    }
  ]
}
```

```json Error Response (File not found) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "FILE_NOT_FOUND",
      "message": "File not found or invalid file type for SMS batches"
    }
  ]
}
```

```json Error Response (Agent number not found) theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "AGENT_NUMBER_NOT_FOUND",
      "message": "Agent number not found or not configured for SMS"
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


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