Skip to main content
POST
/
v1
/
sms
/
batch
Send SMS Batch
curl --request POST \
  --url https://api.bland.ai/v1/sms/batch \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "file_id": "<string>",
  "global": {
    "agent_number": "<string>",
    "agent_message": "<string>",
    "pathway_id": "<string>",
    "pathway_version": 123,
    "start_node_id": "<string>",
    "persona_id": "<string>",
    "request_data": {},
    "channel": "<string>",
    "webhook": "<string>"
  },
  "column_mapping": {}
}
'
{
  "file_id": "file_abc123",
  "global": {
    "agent_number": "+14155551234",
    "pathway_id": "pathway_xyz789",
    "channel": "sms"
  },
  "column_mapping": {
    "customer_name": "request_data"
  }
}
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: 
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 above.
​
global
object
required
Default SMS parameters applied to every message in the batch. The agent_number field is required; all other fields from the Send SMS endpoint are supported as defaults.
​
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:
{
  "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.
​
errors
null|array
null on success, or a list of error objects if the request failed.
{
  "file_id": "file_abc123",
  "global": {
    "agent_number": "+14155551234",
    "pathway_id": "pathway_xyz789",
    "channel": "sms"
  },
  "column_mapping": {
    "customer_name": "request_data"
  }
}