Skip to main content

Create Call Batch

POST Create a new call batch

POST /api/v1/public/call-batches

Create a call batch to schedule AI voice agent calls to one or more contacts. You can start the batch immediately, schedule it for a specific time, or create it in manual mode for later execution.

Authorization​

Authorization: Bearer sk_your_api_key

Request Body​

ParameterTypeRequiredDescription
agent_namestring✅Agent ID (e.g., agt-57949b14)
version_namestring✅Prompt version ID (e.g., pmt-667ddf271b)
voicestring❌Voice name (e.g., Tara, Raj). Defaults to agent's voice.
did_numberstring❌Outbound DID/caller ID number (e.g., 08037236753)
interruptionboolean❌Enable interruption handling. Default: false
use_alternate_numberboolean❌Try alternate number if primary fails. Default: false
start_modestring❌One of: manual, immediate, scheduled. Default: manual
schedule_datestring⚠️Date in YYYY-MM-DD format. Required if start_mode is scheduled.
schedule_timestring⚠️Time in HH:MM format. Required if start_mode is scheduled.
schedule_timezonestring⚠️Timezone (e.g., Asia/Kolkata (IST, UTC+5:30)). Required if start_mode is scheduled.
concurrencyinteger❌Max concurrent calls. Default: account limit.
callback_urlstring❌URL to receive webhook callbacks for this batch
deduplicate_by_phoneboolean❌Remove duplicate phone numbers. Default: true
recording_enabledboolean❌Enable call recording. Default: true
max_duration_seconds_per_callinteger❌Max duration per call in seconds
metadataobject❌Custom key-value metadata for the batch
contactsarray✅Array of contact objects (max 10,000)

Contact Object​

FieldTypeRequiredDescription
contact_idstring✅Your unique identifier for this contact (used as external_id)
namestring❌Contact's display name
phone_numberstring✅Phone number with country code (e.g., 919876543210)
metadataobject❌Custom key-value data passed to the agent during the call
statusstring❌Initial status. Default: pending
Metadata Normalization

Contact metadata keys are automatically normalized. For example, Phone Number, phone_number, and phoneNumber are all treated equivalently. The metadata is made available to the voice agent during the call.

Code Examples​

curl -X POST https://api.staging.techladder.ai/api/v1/public/call-batches \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "agt-57949b14",
    "version_name": "pmt-667ddf271b",
    "voice": "Tara",
    "did_number": "08037236753",
    "interruption": false,
    "use_alternate_number": false,
    "start_mode": "scheduled",
    "schedule_date": "2026-05-15",
    "schedule_time": "14:00",
    "schedule_timezone": "Asia/Kolkata (IST, UTC+5:30)",
    "contacts": [
      {
        "contact_id": "101",
        "name": "John Doe",
        "phone_number": "919876543210",
        "metadata": {
          "Name": "John Doe",
          "Company Name": "Acme Corporation",
          "City": "Delhi",
          "Business Type": "Retailer"
        }
      }
    ]
  }'

Responses​

201 Created​

Batch was created successfully.

{
  "status_code": 201,
  "message": "Call batch created successfully",
  "error": null,
  "data": {
    "schedule_id": "sched_7bac6f2a",
    "agent_id": "agt-57949b14",
    "version_id": "pmt-667ddf271b",
    "status": "pending",
    "start_mode": "scheduled",
    "total_contacts": 1,
    "valid_contacts": 1,
    "duplicate_contacts": 0,
    "scheduled_at": "2026-05-15T08:30:00Z",
    "created_at": "2026-05-14T10:00:00Z"
  }
}

400 Bad Request​

Returned when the batch exceeds the contact limit or references an unknown agent.

{
  "status_code": 400,
  "message": "Contacts array exceeds 10,000 limit",
  "error": {
    "code": "BATCH_SIZE_EXCEEDED",
    "details": ["Maximum 10,000 contacts per batch"]
  },
  "data": null
}

401 Unauthorized​

Returned when the API key is missing or invalid.

{
  "status_code": 401,
  "message": "Missing or invalid API key",
  "error": {
    "code": "UNAUTHORIZED",
    "details": ["Provide a valid Bearer token in the Authorization header"]
  },
  "data": null
}

422 Unprocessable Entity​

Returned when one or more fields fail validation.

{
  "status_code": 422,
  "message": "Invalid request body",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      "agent_name: This field is required",
      "contacts[0].phone_number: Must be at least 10 digits"
    ]
  },
  "data": null
}

429 Too Many Requests​

Returned when the rate limit is exceeded.

{
  "status_code": 429,
  "message": "Rate limit exceeded. Please retry after 30 seconds.",
  "error": {
    "code": "RATE_LIMITED",
    "details": ["Maximum 300 requests per minute"]
  },
  "data": null
}