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.

Prefer the idempotent endpoint

PUT /api/v1/public/call-batches accepts the same request body plus an idempotency_key, and safely no-ops on retries instead of creating a duplicate batch. It's the preferred way to create batches — see Create Batch (Idempotent).

Authorization​

Authorization: Bearer sk_your_api_key

Request Body​

ParameterTypeRequiredDescription
agent_id / agent_namestring✅ (one of)Agent ID (e.g., agt-57949b14) or agent name. At least one is required.
version_id / version_namestring✅ (one of)Prompt version ID (e.g., pmt-667ddf271b) or version name. At least one is required.
voicestring❌Voice name (e.g., Tara, Raj). Defaults to the agent's voice.
did_number_idstring❌Outbound DID/caller ID number to dial from (e.g., 08037236753). Auto-selected from your account's available numbers if omitted.
interruptionboolean✅Enable interruption handling. Only takes effect if interruption is enabled on your account.
use_alternate_numberboolean✅Try the contact's alternate number if the primary fails.
start_modestring✅One of: manual, immediate, scheduled. No default — must be supplied.
schedule_datestring✅Date in YYYY-MM-DD format. Its value only affects dispatch timing when start_mode is scheduled.
schedule_timestring✅Time in HH:MM format. Its value only affects dispatch timing when start_mode is scheduled.
schedule_timezonestring✅Timezone (e.g., Asia/Kolkata (IST, UTC+5:30)). Its value only affects dispatch timing when start_mode is scheduled.
concurrencyinteger❌Max concurrent calls. Default: your account's configured batch concurrency limit.
callback_urlstring❌URL to receive webhook callbacks for this batch
deduplicate_by_phoneboolean❌Remove duplicate phone numbers within the batch. Default: false
recording_enabledboolean❌Enable call recording. Default: your agent/account's configured setting.
max_duration_seconds_per_callinteger❌Max duration per call in seconds
metadataobject❌Custom key-value metadata for the batch
contactsarray✅Array of contact objects (at least 1)

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.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": {
    "batch_id": "sched_7bac6f2a",
    "agent_id": "agt-57949b14",
    "version_id": "pmt-667ddf271b",
    "status": "pending",
    "start_mode": "scheduled",
    "total_contacts": 1,
    "accepted_contacts": 1,
    "rejected_contacts": 0,
    "validation_errors": [],
    "concurrency": 20,
    "created_at": "2026-05-14T10:00:00Z",
    "idempotent": false
  }
}

If any contacts fail validation (e.g. invalid phone number), the batch is still created with the valid contacts — check rejected_contacts and validation_errors for details:

{
  "status_code": 201,
  "message": "Call batch created with validation errors",
  "error": null,
  "data": {
    "batch_id": "sched_7bac6f2a",
    "agent_id": "agt-57949b14",
    "version_id": "pmt-667ddf271b",
    "status": "pending",
    "start_mode": "scheduled",
    "total_contacts": 2,
    "accepted_contacts": 1,
    "rejected_contacts": 1,
    "validation_errors": [
      {
        "index": 2,
        "external_id": "102",
        "field": "phone_number",
        "message": "Invalid Indian mobile number"
      }
    ],
    "concurrency": 20,
    "created_at": "2026-05-14T10:00:00Z",
    "idempotent": false
  }
}

401 Unauthorized​

Returned when the API key is missing or invalid. Auth and not-found errors are not wrapped in the standard envelope — they return FastAPI's default shape.

{
  "detail": "Invalid API key"
}

404 Not Found​

Returned when the referenced agent or prompt version doesn't exist on your account.

{
  "detail": "Agent 'agt-unknown' not found"
}

422 Unprocessable Entity — request validation​

Returned when a required field is missing or a field fails type/format validation. This case is wrapped in the standard envelope.

{
  "status_code": 422,
  "message": "Missing required parameter",
  "error": {
    "code": "MISSING_PARAMETER",
    "details": [
      "agent_id: Field required",
      "contacts.0.phone_number: String should have at least 8 characters"
    ]
  },
  "data": null
}

422 Unprocessable Entity — business rule​

Returned for domain-level failures caught after the request body parses successfully (e.g. every contact was rejected, or the selected voice/DID number isn't available on your account). This case is not wrapped in the envelope.

{
  "detail": "All contacts are invalid"
}