API reference

Batches

Call a list of contacts from a CSV file with one agent.

A batch is a CSV file of contacts tied to one agent. You upload the file, schedule the batch, and the platform creates one execution per row at the scheduled time. The account's concurrency limit decides how many of those calls run at once. A batch completes when every one of its calls has reached a final status.

All routes need Authorization: Bearer <key>. Batch ids are 32 hexadecimal characters. An unknown, deleted or foreign batch id answers 404 with Batch not found.

Operation	Method and path
Create a batch	`POST /batches`
Schedule a batch	`POST /batches/{batch_id}/schedule`
Stop a batch	`POST /batches/{batch_id}/stop`
Get a batch	`GET /batches/{batch_id}`
List an agent's batches	`GET /batches/{agent_id}/all`
List a batch's executions	`GET /batches/{batch_id}/executions`
List a batch's executions by page	`GET /v2/batches/{batch_id}/executions`
Delete a batch	`DELETE /batches/{batch_id}`

The CSV file

The file must be UTF-8 text with a header row. A spreadsheet or PDF renamed to .csv is refused.
A contact_number column is required. Values must be E.164, for example +919876500012. Spaces and hyphens inside a number are removed.
Every other column becomes a prompt variable for that row, available as {column_name} in the agent's welcome message and prompts.
Rows without a valid number are counted in total_contacts but not in valid_contacts, and are not called.
When the account requires consent (see Compliance), rows need a truthy consent column.
The upload is limited to 26 MB.

text

contact_number,name,due_date
+919876500012,Asha,2026-11-01
+919876500013,Ravi,2026-11-04

Batch statuses are created, scheduled, running, completed, stopped and failed (the agent was deleted before the batch started).

Operations

Create a batch

POST /batches

Uploads the contact file and creates the batch in status created. Nothing is called until you schedule it. The request is multipart/form-data.

Auth: API key or session token. Role: member and up. When the operator sets REQUIRE_VERIFIED_EMAIL, the login must have a verified email address.

This route accepts an Idempotency-Key header for uploads up to 30 MB; see Idempotency.

Parameter	In	Type	Required	Description
`agent_id`	form	string (UUID)	yes	The agent that makes the calls.
`file`	form	file	yes	The CSV file.
`from_phone_numbers`	form	string, repeatable	no	Caller IDs in E.164. Send the field several times, or once as a JSON array or a comma-separated list. Rows rotate through the numbers in order.
`retry_config`	form	string (JSON object)	no	Automatic retries, as in Make a call. `max_retries` must be 1 to 3.
`webhook_url`	form	string	no	Webhook for this batch's calls. Overrides the agent's webhook.

Request

bash

curl -X POST https://api.sevennadi.si/batches \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -F "agent_id=f412f2b1-3493-4458-bcf2-8676cc798edd" \
  -F "file=@contacts.csv;type=text/csv" \
  -F "from_phone_numbers=+918045550100" \
  -F 'retry_config={"enabled": true, "max_retries": 2}'

Response 201 Created

json

{
  "batch_id": "3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b",
  "state": "created",
  "valid_contacts": 2,
  "total_contacts": 2,
  "skipped_contacts": 0,
  "skipped_rows": []
}

skipped_rows previews the rows that will not be called when the batch starts, with a reason each (do-not-call list, missing consent). The final list is set when the batch runs.

Errors

Status	Message
400	`The CSV must have a contact_number column`
400	`The CSV has no valid contact_number (E.164, e.g. +919876543210)`
400	`retry_config must be a JSON object`
400	`retry_config.max_retries must be between 1 and 3`
400	`from_phone_numbers must be a list of phone numbers`
400	`Invalid from_phone_number <number>`
403	`Trial accounts can only call verified phone numbers. Verify <numbers> before calling.`
404	`Agent not found`
413	`The request body is larger than 26 MB`

Schedule a batch

POST /batches/{batch_id}/schedule

Sets the start time of a batch. The platform rounds the time up to a 10-minute boundary; the operator can set a different step. A batch that is created or scheduled can be scheduled again, which moves its start. The request is form-encoded.

Auth: API key or session token. Role: member and up. When the operator sets REQUIRE_VERIFIED_EMAIL, the login must have a verified email address.

This route accepts an Idempotency-Key header.

Parameter	In	Type	Required	Description
`batch_id`	path	string	yes	The batch.
`scheduled_at`	form	string	yes	ISO 8601 timestamp with a UTC offset, no sooner than 2 minutes from now.
`bypass_call_guardrails`	form	boolean	no	Ignore the agent's calling hours. Default `false`.

Request

bash

curl -X POST https://api.sevennadi.si/batches/3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b/schedule \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -F "scheduled_at=2026-10-14T09:00:00+05:30"

Response 200 OK

json

{"message": "success", "state": "scheduled"}

When the batch starts, each row is checked against the do-not-call list, consent and the daily frequency cap. Rows that fail are listed in the batch's skipped_rows and are not called. Rows outside the agent's calling hours get an execution in rescheduled for the next allowed start.

Errors

Status	Message
400	`Batch is already <status>`
400	`scheduled_at must be an ISO 8601 timestamp with a UTC offset`
400	`scheduled_at must include a UTC offset, e.g. +00:00`
400	`Scheduled time should be at least 2 minutes in the future`
404	`Batch not found`

Stop a batch

POST /batches/{batch_id}/stop

Stops a scheduled or running batch. Calls not dialed yet become stopped; calls in progress are hung up by their workers. A stopped batch cannot be started again.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`batch_id`	path	string	yes	The batch.

Request

bash

curl -X POST https://api.sevennadi.si/batches/3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b/stop \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{"message": "success", "state": "stopped"}

Errors

Status	Message
404	`Batch not found`
404	`Batch is not queued or running`. This one body has no `error` field: it is `{"message": "Batch is not queued or running"}`.

Get a batch

GET /batches/{batch_id}

Returns a batch with its progress.

Auth: API key or session token. Role: viewer and up.

Parameter	In	Type	Required	Description
`batch_id`	path	string	yes	The batch.

Request

bash

curl https://api.sevennadi.si/batches/3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{
  "batch_id": "3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b",
  "humanized_created_at": "5 minutes ago",
  "created_at": "2026-10-13T07:40:00Z",
  "updated_at": "2026-10-13T07:41:10Z",
  "status": "running",
  "scheduled_at": "2026-10-13T07:50:00Z",
  "from_phone_number": "+918045550100",
  "from_phone_numbers": ["+918045550100"],
  "file_name": "contacts.csv",
  "valid_contacts": 2,
  "total_contacts": 2,
  "execution_status": {"completed": 1, "in-progress": 1},
  "skipped_contacts": 0,
  "skipped_rows": []
}

execution_status counts the batch's executions by status. paused_reason is added with the value balance-low while a running batch waits for a wallet top-up. Fields with no value are left out.

Errors

Status	Message
404	`Batch not found`

List an agent's batches

GET /batches/{agent_id}/all

Returns the batches of one agent, newest first. The list is not paginated.

Auth: API key or session token. Role: viewer and up.

Parameter	In	Type	Required	Description
`agent_id`	path	string (UUID)	yes	The agent.

Request

bash

curl https://api.sevennadi.si/batches/f412f2b1-3493-4458-bcf2-8676cc798edd/all \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

An array of batch objects, each as in Get a batch.

Errors

Status	Message
404	`Agent not found`

List a batch's executions

GET /batches/{batch_id}/executions

Returns the batch's executions as a plain array, oldest first, at most 1,000: a larger batch gets only its first 1,000. For large batches use the paged route below.

Auth: API key or session token. Role: viewer and up.

Parameter	In	Type	Required	Description
`batch_id`	path	string	yes	The batch.

Request

bash

curl https://api.sevennadi.si/batches/3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b/executions \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

An array of execution objects. Each carries batch_id, batch_run_details and the row's values under context_details.recipient_data.

Errors

Status	Message
404	`Batch not found for given batch_id <batch_id>`

List a batch's executions by page

GET /v2/batches/{batch_id}/executions

Returns the batch's executions one page at a time, oldest first.

Auth: API key or session token. Role: viewer and up.

Parameter	In	Type	Required	Description
`batch_id`	path	string	yes	The batch.
`page_number`	query	integer	no	Starts at 1. Default `1`.
`page_size`	query	integer	no	1 to 50. Default `20`.

Request

bash

curl "https://api.sevennadi.si/v2/batches/3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b/executions?page_number=1&page_size=50" \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{
  "page_number": 1,
  "page_size": 50,
  "total": 2,
  "has_more": false,
  "data": [
    {"id": "0b6c2c4e-7a55-4b0f-9a07-3d6b1f9f2a11", "batch_id": "3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b", "status": "completed"},
    {"id": "9d1e7f3a-2b4c-4d5e-8f60-1a2b3c4d5e6f", "batch_id": "3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b", "status": "in-progress"}
  ]
}

Each entry of data is a full execution object.

Errors

Status	Message
400	`page_number must be >= 1 and page_size between 1 and 50`
404	`Batch not found for given batch_id <batch_id>`

Delete a batch

DELETE /batches/{batch_id}

Deletes a batch. A scheduled or running batch is stopped first. The executions already created stay readable through the Executions routes.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`batch_id`	path	string	yes	The batch.

Request

bash

curl -X DELETE https://api.sevennadi.si/batches/3f0e2c9a6b7d4e1f8a2b5c6d7e8f9a0b \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{"message": "success", "state": "deleted"}

Errors

Status	Message
404	`Batch not found`