Skip to main content

Create Call Batch (Idempotent)

PUT Create a new call batch idempotently

PUT /api/v1/public/call-batches

Create a call batch the same way as POST /call-batches, but scoped to a caller-supplied idempotency_key. This is the preferred way to create batches: if a network error or timeout forces you to retry a request, retrying with the same key returns the batch that was already created instead of scheduling a duplicate.

  • The first request for a given idempotency_key schedules the batch and returns 201 Created.
  • Any later request with the same idempotency_key (from the same account) returns the original batch unchanged with 200 OK and idempotent: true — no new batch is created, and the contacts/settings from the retry are ignored.
  • idempotency_key is scoped per account — reusing a key across different accounts does not cause a collision.

Authorization​

Authorization: Bearer sk_your_api_key

Request Body​

Accepts every field from POST /call-batches, plus:

ParameterTypeRequiredDescription
idempotency_keystring✅Your unique key for this create attempt (1–128 characters). Reuse it to safely retry.

Code Examples​

curl -X PUT https://api.techladder.ai/api/v1/public/call-batches \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "campaign-2026-05-15-batch-1",
    "agent_name": "agt-57949b14",
    "version_name": "pmt-667ddf271b",
    "voice": "Tara",
    "did_number_id": "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​

Returned the first time this idempotency_key is used — a new batch was scheduled.

{
  "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
  }
}

200 OK​

Returned when this idempotency_key was already used for a previous request — the existing batch is returned as-is, and no new batch is scheduled. Note idempotent: true.

{
  "status_code": 200,
  "message": "Call batch already exists for this idempotency key",
  "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": true
  }
}

401 Unauthorized​

Returned when the API key is missing or invalid. This is not wrapped in the standard envelope.

{
  "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 — including idempotency_key — is missing or fails validation. This case is wrapped in the standard envelope.

{
  "status_code": 422,
  "message": "Missing required parameter",
  "error": {
    "code": "MISSING_PARAMETER",
    "details": [
      "idempotency_key: Field required"
    ]
  },
  "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). This case is not wrapped in the envelope.

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