Create an outbound batch

Creates an outbound batch under conversations:write and starts dialing right away, at most five calls at a time per organization. Send up to 5000 recipients as JSON, or a csvUrl (https) to a CSV with a header row: phone_number (E.164) is required; name, first_message, prompt, and from_channel_id map to the recipient fields; any other column becomes a dynamic variable. The number each call leaves from is resolved per recipient: its fromChannelId, then the batch fromChannelId, then the Agent’s own outbound channel, then the organization’s platform-managed line. Batch-level firstMessage and prompt apply unless a recipient overrides them; are substituted by the voice provider. Calls start right away unless startAt is given; an optional schedule limits them to weekday windows in a time zone; at endAt whatever is still pending is cancelled as expired. Each accepted call becomes an ordinary outbound Conversation with originKind automation; a recipient settles only after that Conversation’s post-call evaluation, and retries (retryOn) when nobody answered or the evaluation failed. Send idempotencyKey so a retried request returns the same batch instead of creating a second one.

POST

outbound-batches

curl --request POST \
  --url https://api.getarbol.com/v1/outbound-batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({agentId: 'agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31', name: '<string>'})
};

fetch('https://api.getarbol.com/v1/outbound-batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.getarbol.com/v1/outbound-batches"

payload = {
    "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
    "name": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "counts": {
    "calling": 4503599627370495,
    "cancelled": 4503599627370495,
    "completed": 4503599627370495,
    "failed": 4503599627370495,
    "pending": 4503599627370495,
    "total": 4503599627370495
  },
  "createdAt": "2026-08-29T14:30:00Z",
  "endAt": "2026-08-29T14:30:00Z",
  "firstMessage": "<string>",
  "fromChannelId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "idempotencyKey": "<string>",
  "name": "<string>",
  "prompt": "<string>",
  "retries": 2,
  "retryDelaySeconds": 43230,
  "retryOn": [
    "noAnswer"
  ],
  "schedule": {
    "timezone": "America/Bogota",
    "windows": [
      {
        "days": [
          "mon"
        ],
        "end": "09:30",
        "start": "09:30"
      }
    ]
  },
  "startAt": "2026-08-29T14:30:00Z",
  "status": "queued",
  "updatedAt": "2026-08-29T14:30:00Z"
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "code": "custom",
        "message": "<string>",
        "path": [
          "<string>"
        ]
      }
    ],
    "truncated": true
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "<string>",
  "data": {
    "missingPermissions": [
      "agents:read"
    ]
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "CONFLICT",
  "status": 409,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "UNPROCESSABLE_CONTENT",
  "status": 422,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "TOO_MANY_REQUESTS",
  "status": 429,
  "message": "<string>",
  "data": {
    "retryAfterSeconds": 123
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "SERVICE_UNAVAILABLE",
  "status": 503,
  "message": "<string>",
  "data": "<unknown>"
}

Authorizations

Authorization

string

header

required

Organization-scoped Auth0 user access token issued to an approved first-party client or exchanged by a trusted OBO resource server.

Body

application/json

agentId

string

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

name

string

required

Required string length: 1 - 200

endAt

string<date-time>

Stop starting calls at this instant: recipients still pending become cancelled with failureReason expired; calls in progress finish. Absent: run until every recipient is settled.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

firstMessage

string

Replaces the Agent's first message for every call in the batch. Supports {{dynamic_variables}}.

Required string length: 1 - 2000

fromChannelId

string

Connected voice channel to call from. Resolution order per call: recipient fromChannelId, then this, then the Agent's own outbound channel, then the organization's platform-managed line.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

idempotencyKey

string

Caller-generated key. Repeating a request with the same key returns the batch created the first time instead of calling everyone again.

Required string length: 8 - 200

Example:

"campaign-2026-09-recordatorios"

prompt

string

Replaces the Agent's system prompt for every call in the batch. The Agent's stored configuration is untouched.

Required string length: 1 - 20000

retries

integer

default:0

Extra attempts per recipient when a call does not count as successful (see retryOn). 0 dials each number once.

Required range: 0 <= x <= 5

retryDelaySeconds

integer

default:900

Wait between attempts to the same number.

Required range: 60 <= x <= 86400

retryOn

enum<string>[]

What earns a retry. noAnswer: the call closed without a single message. failure: the Conversation's post-call success evaluation is failure (voicemail, goal not met, per the Agent's assessments). Drop failure when a refusal must not be called again.

Maximum array length: 2

Available options:

noAnswer,

failure

schedule

Calling schedule · object

Only start calls inside these windows; outside them the batch waits for the next opening. Absent: any time.

Show child attributes

startAt

string<date-time>

Do not start any call before this instant. Absent: start right away (inside the schedule, if one is given).

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

csvUrl

string<uri>

https link to a CSV (max 5 MB, header row required). Alternative to recipients. Downloaded once, when the batch is created.

Maximum string length: 2000

Example:

"https://files.example.com/campaign-september.csv"

recipients

Outbound batch recipient input · object[]

Required array length: 1 - 5000 elements

Show child attributes

Response

agentId

string

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

counts

Outbound batch recipient counts · object

required

Show child attributes

createdAt

string<date-time>

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

endAt

string<date-time> | null

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

firstMessage

string | null

required

Required string length: 1 - 2000

fromChannelId

string | null

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

string

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

idempotencyKey

string | null

required

Maximum string length: 200

name

string

required

Maximum string length: 200

prompt

string | null

required

Required string length: 1 - 20000

retries

integer

required

Required range: 0 <= x <= 5

retryDelaySeconds

integer

required

Required range: 60 <= x <= 86400

retryOn

enum<string>[]

required

Maximum array length: 2

Available options:

noAnswer,

failure

schedule

Calling schedule · object | null

required

Weekday windows on the wall clock of timezone. Example: Monday and Tuesday 04:00-14:00 and 20:00-22:00, Friday 10:00-11:00.

Show child attributes

startAt

string<date-time> | null

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

status

enum<string>

required

queued: no call placed yet. running: at least one call placed. completed: every recipient settled. cancelled: pending recipients were dropped; calls already placed finish normally.

Available options:

queued,

running,

completed,

cancelled

updatedAt

string<date-time>

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

⌘I

Create an outbound batch

curl --request POST \
  --url https://api.getarbol.com/v1/outbound-batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({agentId: 'agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31', name: '<string>'})
};

fetch('https://api.getarbol.com/v1/outbound-batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.getarbol.com/v1/outbound-batches"

payload = {
    "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
    "name": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "counts": {
    "calling": 4503599627370495,
    "cancelled": 4503599627370495,
    "completed": 4503599627370495,
    "failed": 4503599627370495,
    "pending": 4503599627370495,
    "total": 4503599627370495
  },
  "createdAt": "2026-08-29T14:30:00Z",
  "endAt": "2026-08-29T14:30:00Z",
  "firstMessage": "<string>",
  "fromChannelId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "idempotencyKey": "<string>",
  "name": "<string>",
  "prompt": "<string>",
  "retries": 2,
  "retryDelaySeconds": 43230,
  "retryOn": [
    "noAnswer"
  ],
  "schedule": {
    "timezone": "America/Bogota",
    "windows": [
      {
        "days": [
          "mon"
        ],
        "end": "09:30",
        "start": "09:30"
      }
    ]
  },
  "startAt": "2026-08-29T14:30:00Z",
  "status": "queued",
  "updatedAt": "2026-08-29T14:30:00Z"
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "code": "custom",
        "message": "<string>",
        "path": [
          "<string>"
        ]
      }
    ],
    "truncated": true
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "<string>",
  "data": {
    "missingPermissions": [
      "agents:read"
    ]
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "CONFLICT",
  "status": 409,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "UNPROCESSABLE_CONTENT",
  "status": 422,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "TOO_MANY_REQUESTS",
  "status": 429,
  "message": "<string>",
  "data": {
    "retryAfterSeconds": 123
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "SERVICE_UNAVAILABLE",
  "status": 503,
  "message": "<string>",
  "data": "<unknown>"
}

Overview

Endpoints

Create an outbound batch

Authorizations

Body

Response