Create a draft batch

cURL

curl --request POST 'https://api.brightalk.ai/batches' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: createBatch-example-001" \
  --data '{"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]}'

const response = await fetch("https://api.brightalk.ai/batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
    "Brightalk-Version": "2026-07-16",
    "Content-Type": "application/json",
    "Idempotency-Key": "createBatch-example-001",
  },
  body: JSON.stringify({"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]}),
});
console.log(response.status, await response.json());

import os
import requests

response = requests.request(
    "POST",
    "https://api.brightalk.ai/batches",
    headers={
    "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
    "Brightalk-Version": "2026-07-16",
    "Content-Type": "application/json",
    "Idempotency-Key": "createBatch-example-001",
    },
    json={"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]},
)
print(response.status_code, response.json())

{
  "id": "bat_demo_001",
  "name": "Renewal reminders",
  "agent_id": "agt_demo_001",
  "total_recipients": 2,
  "pending_recipients": 2,
  "queued_recipients": 0,
  "in_progress_recipients": 0,
  "completed_recipients": 0,
  "failed_recipients": 0,
  "cancelled_recipients": 0,
  "answered_recipients": 0,
  "no_answer_recipients": 0,
  "busy_recipients": 0,
  "created_at": "2026-07-20T01:00:00Z",
  "updated_at": "2026-07-20T01:00:00Z",
  "scheduled_start_at": "2026-07-20T01:00:00Z",
  "calling_window": {
    "time_zone": "Asia/Taipei",
    "weekdays": [
      "monday",
      "tuesday",
      "wednesday",
      "thursday",
      "friday"
    ],
    "start_time": "09:00",
    "end_time": "18:00"
  },
  "started_at": "2026-07-20T01:00:00Z",
  "paused_at": "2026-07-20T01:00:00Z",
  "completed_at": "2026-07-20T01:00:00Z",
  "cancelled_at": "2026-07-20T01:00:00Z"
}

POST

batches

cURL

curl --request POST 'https://api.brightalk.ai/batches' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: createBatch-example-001" \
  --data '{"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]}'

const response = await fetch("https://api.brightalk.ai/batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
    "Brightalk-Version": "2026-07-16",
    "Content-Type": "application/json",
    "Idempotency-Key": "createBatch-example-001",
  },
  body: JSON.stringify({"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]}),
});
console.log(response.status, await response.json());

import os
import requests

response = requests.request(
    "POST",
    "https://api.brightalk.ai/batches",
    headers={
    "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
    "Brightalk-Version": "2026-07-16",
    "Content-Type": "application/json",
    "Idempotency-Key": "createBatch-example-001",
    },
    json={"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]},
)
print(response.status_code, response.json())

{
  "id": "bat_demo_001",
  "name": "Renewal reminders",
  "agent_id": "agt_demo_001",
  "total_recipients": 2,
  "pending_recipients": 2,
  "queued_recipients": 0,
  "in_progress_recipients": 0,
  "completed_recipients": 0,
  "failed_recipients": 0,
  "cancelled_recipients": 0,
  "answered_recipients": 0,
  "no_answer_recipients": 0,
  "busy_recipients": 0,
  "created_at": "2026-07-20T01:00:00Z",
  "updated_at": "2026-07-20T01:00:00Z",
  "scheduled_start_at": "2026-07-20T01:00:00Z",
  "calling_window": {
    "time_zone": "Asia/Taipei",
    "weekdays": [
      "monday",
      "tuesday",
      "wednesday",
      "thursday",
      "friday"
    ],
    "start_time": "09:00",
    "end_time": "18:00"
  },
  "started_at": "2026-07-20T01:00:00Z",
  "paused_at": "2026-07-20T01:00:00Z",
  "completed_at": "2026-07-20T01:00:00Z",
  "cancelled_at": "2026-07-20T01:00:00Z"
}

Authorizations

Authorization

string

header

required

Use a server-side Brightalk API key in the Authorization header.

Headers

Brightalk-Version

string

default:2026-07-16

Selects the date-based API version. Omission uses the organization’s pinned default.

Allowed value: "2026-07-16"

X-Request-Id

string

A caller-generated correlation value matching [A-Za-z0-9._:-]{1,64}. Invalid values are replaced.

Maximum string length: 64

Pattern: ^[A-Za-z0-9._:-]{1,64}$

Idempotency-Key

string

required

A nonsecret key retained for 24 hours. Reuse only for a semantically identical request.

Required string length: 1 - 255

Pattern: ^(?=.{1,255}$)[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$

Body

application/json

JSON request body. The raw encoded body is limited to 1 MiB and unknown fields are rejected.

Option 1
Option 2

agent_id

string

required

An opaque resource identifier.

Required string length: 1 - 255

Example:

"agt_demo_001"

contact_ids

string[]

required

Required array length: 1 - 1000 elements

An opaque resource identifier.

Required string length: 1 - 255

Example:

["con_demo_001", "con_demo_002"]

name

string

Leading and trailing whitespace is trimmed; the remaining value must contain 1–200 characters.

Pattern: ^\s*\S(?:[\s\S]{0,198}\S)?\s*$

Example:

"Renewal reminders"

schedule

object

Show child attributes

Response

Draft batch created.

string

required

An opaque resource identifier.

Required string length: 1 - 255

Example:

"bat_demo_001"

status

enum<string>

required

Available options:

draft,

scheduled,

queued,

in_progress,

paused,

completed,

failed,

cancelled

name

string

required

Example:

"Renewal reminders"

agent_id

string

required

An opaque resource identifier.

Required string length: 1 - 255

Example:

"agt_demo_001"

total_recipients

integer

required

Required range: x >= 0

Example:

2

pending_recipients

integer

required

Required range: x >= 0

Example:

2

queued_recipients

integer

required

Required range: x >= 0

Example:

0

in_progress_recipients

integer

required

Required range: x >= 0

Example:

0

completed_recipients

integer

required

Required range: x >= 0

Example:

0

failed_recipients

integer

required

Required range: x >= 0

Example:

0

cancelled_recipients

integer

required

Required range: x >= 0

Example:

0

answered_recipients

integer

required

Required range: x >= 0

Example:

0

no_answer_recipients

integer

required

Required range: x >= 0

Example:

0

busy_recipients

integer

required

Required range: x >= 0

Example:

0

created_at

string<date-time>

required

When the batch was created.

Example:

"2026-07-20T01:00:00Z"

updated_at

string<date-time>

required

When the batch was last updated.

Example:

"2026-07-20T01:00:00Z"

scheduled_start_at

string<date-time>

The configured earliest start instant.

Example:

"2026-07-20T01:00:00Z"

calling_window

object

One contiguous daily calling window. The runtime requires end_time to be later than start_time; x-brightalk-end-after-start records that checker-only cross-field rule because standard JSON Schema cannot compare two time strings.

Show child attributes

started_at

string<date-time>

When dispatch began.

Example:

"2026-07-20T01:00:00Z"

paused_at

string<date-time>

When the batch was paused.

Example:

"2026-07-20T01:00:00Z"

completed_at

string<date-time>

When the batch reached completion.

Example:

"2026-07-20T01:00:00Z"

cancelled_at

string<date-time>

When the batch was cancelled.

Example:

"2026-07-20T01:00:00Z"

List batches Retrieve a batch

⌘I

Get started

API fundamentals

Core concepts

Guides

Release information

API reference

Authorizations

Headers

Body

Response