Skip to main content
POST

​
Overview

After creating a batch you can enqueue contact records that the dialer should process. Each record can include any custom fields your agent definition expects. Validation runs against the agent’s variable schema so you catch missing data before the dialer starts.

​
Prerequisites

  • You created the batch and captured its batchId.
  • All required agent variables are present in every contact.
  • The API key you use owns the batch.

​
Request

​
string
required
Workspace API key. Must match the owner of the target batch.
​
string
required
Identifier returned by POST /api/call/createBatch.
​
array[object]
required
Array of call records to be added to the batch. Each object MUST include phoneNumber. All other fields are flexible and determined by your agent’s configuration. The system automatically chunks large arrays (1000 records per chunk) for efficient processing.

​
Response

​
string
required
A human-readable message indicating the outcome.
​
boolean
required
Indicates whether the operation was entirely successful. If false and code is 207, check data.failedChunks.
​
integer
required
The HTTP status code (200 for full success, 207 for partial success).
​
string
Error message, if any.
​
object
Contains details about the operation.
​
integer
required
Total number of call records successfully added to the batch across all chunks.
​
array[string]
required
Array of call record IDs that were inserted or updated.
​
array[object]
Present when status is false and code is 207. Array of chunk processing failures, each containing chunkNum and error message.

​
Error Handling

  • 400 Bad Request – Missing batchId, empty callData array, or validation failure.
  • 403 Forbidden – Invalid or missing API key, or API key doesn’t own the batch.
  • 404 Not Found – Batch not found, or no agent found for the batch’s calling numbers.
  • 207 Partial Content – Some chunks processed successfully while others failed. Check failedChunks for details.
  • 500 Internal Server Error – Server error during processing; retry with exponential backoff.
Flexible Parameters:The callData array accepts any custom key-value pairs beyond the required phoneNumber field. You can include any parameters your agent needs:
  • Customer identifiers (e.g., account_id, customer_id, unique_id)
  • Custom data fields (e.g., custom_field_1, custom_field_2, priority)
  • Business-specific data (e.g., order_amount, subscription_tier, category)
  • Any other data your AI agent requires for the conversation
Important: Each object in callData MUST include phoneNumber. All other fields are flexible and determined by your agent’s configuration.
Processing Details:
  • Large arrays are automatically chunked into batches of 1000 records for efficient processing
  • Each call record is validated against the agent’s required variables
  • Existing calls with the same phone number are updated if they have a “pending” status
  • Completed calls create new phone log entries
  • The system automatically starts the calling service after successful insertion
  • Timezone information is applied to each call record if not provided
You can safely enqueue thousands of contacts in a single request. The system handles chunking automatically. Monitor the response for status: false and code: 207 to identify any failed chunks that may need retry.

Authorizations

​
Authorization
string
header
required

Bearer token authentication for workspace access

Body

application/json
​
batchId
string
required
Example:

"64e5f12345abcdef98765432"

​
callData
object[]
required

Array of call records. Each object MUST include phoneNumber. All other fields are flexible and determined by your agent configuration.

Response

Calls enqueued