Voice API Reference

The Agentive Voice API gives your application programmatic access to the same calling stack that powers the dashboard. Place a single outbound call, read a verification code out to a customer, run a saved campaign for one number, or poll the result of any call you started.

Every amount is in Indian Rupees (INR). Every timestamp is in Indian Standard Time (IST), in ISO 8601 format. Every request is authenticated with a publishable key and a secret, and every response uses one consistent JSON envelope so your integration code stays simple.

Every endpoint path below is relative to this base URL.

https://voice.agentive.co.in/api/public/v1

Every request must be authenticated with two credentials issued to your account.

View and rotate both keys from the API tab in your dashboard. The secret is shown in full only once, when it is first generated or rotated; afterwards it is masked. If you lose it, rotate to generate a new pair, and the old secret stops working immediately.

The header form is recommended because it keeps the secret out of request bodies and most log formats. If you send the secret in both the header and the body, the header value is used. There is a single set of live credentials per account; both keys begin with a _live_ prefix and every call is processed against your live account.

curl https://voice.agentive.co.in/api/public/v1/account \
  -u pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl https://voice.agentive.co.in/api/public/v1/calls \
  -H "x-api-key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "x-api-secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "type": "audio_blast", "number": "9812345678", "audio_id": 12 }'

Every response is JSON and uses one consistent envelope.

{
  "status": "success",
  "code": 200,
  "unique_id": "run_4821",
  "reference_id": "order-99213",
  "details": "Call queued."
}

Successful responses may include extra fields alongside the envelope. These are documented per endpoint (for example request_id and expires_in_sec on OTP send, verified on verify, call_status on status).

Error responses never include internal infrastructure detail. A failed call placement returns a neutral message such as "Could not place the call right now. Please retry."

{
  "status": "error",
  "code": 400,
  "unique_id": null,
  "reference_id": "order-99213",
  "details": "A valid Indian mobile number is required."
}

Requests are limited per account to 120 requests per minute. The limit is keyed to your account, so traffic from one account never throttles another, and an office behind a single shared IP is not treated as one caller.

When you exceed the limit you receive HTTP 429 with:

{
  "status": "error",
  "code": 429,
  "details": "Too many requests. Please slow down and retry shortly."
}

Standard rate-limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) are returned on responses so you can pace your requests.

The write endpoints place a call, trigger a saved campaign, send a voice verification code, and verify a code. The read endpoints fetch a single call's status, list your calls, download a recording, list your campaigns, and report your account balance.

{
  "status": "success",
  "code": 200,
  "unique_id": "run_4821",
  "reference_id": "order-99213",
  "details": "Call queued."
}

curl https://voice.agentive.co.in/api/public/v1/calls \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "audio_blast",
    "number": "9812345678",
    "audio_id": 12,
    "reference_id": "order-99213"
  }'

{
  "type": "press1",
  "number": "9812345678",
  "audio_id": 18,
  "dtmf_map": { "1": "connect_agent" },
  "reference_id": "promo-march"
}

{
  "status": "success",
  "code": 200,
  "unique_id": "run_4822",
  "reference_id": "lead-5567",
  "details": "Call queued."
}

curl https://voice.agentive.co.in/api/public/v1/campaigns/57/trigger \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "number": "9812345678", "reference_id": "lead-5567" }'

{
  "status": "success",
  "code": 200,
  "unique_id": "5f3c8b2a-1d4e-4a9c-9e7b-2c6f0a1b3d8e",
  "reference_id": "signup-7781",
  "details": "Verification call queued.",
  "request_id": "5f3c8b2a-1d4e-4a9c-9e7b-2c6f0a1b3d8e",
  "expires_in_sec": 600
}

curl https://voice.agentive.co.in/api/public/v1/otp/send \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "number": "9812345678", "length": 4, "ttl": 600, "reference_id": "signup-7781" }'

{
  "status": "success",
  "code": 200,
  "unique_id": "5f3c8b2a-1d4e-4a9c-9e7b-2c6f0a1b3d8e",
  "reference_id": "signup-7781",
  "details": "Code verified.",
  "request_id": "5f3c8b2a-1d4e-4a9c-9e7b-2c6f0a1b3d8e",
  "verified": true
}

{
  "status": "error",
  "code": 401,
  "details": "Incorrect code.",
  "verified": false,
  "attempts_left": 2
}

curl https://voice.agentive.co.in/api/public/v1/otp/verify \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "request_id": "5f3c8b2a-1d4e-4a9c-9e7b-2c6f0a1b3d8e", "code": "1234" }'

{
  "status": "success",
  "code": 200,
  "unique_id": "run_4821",
  "reference_id": null,
  "details": "answered",
  "call_status": "answered",
  "duration_sec": 17
}

{
  "status": "success",
  "code": 200,
  "unique_id": "5f3c8b2a-1d4e-4a9c-9e7b-2c6f0a1b3d8e",
  "reference_id": "signup-7781",
  "details": "verified",
  "call_status": "verified",
  "verified": true,
  "attempts": 1,
  "max_attempts": 3
}

curl https://voice.agentive.co.in/api/public/v1/calls/run_4821 \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..."

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "unique_id": "run_4821",
      "call_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "direction": "outbound",
      "from_number": "07965318581",
      "to_number": "+919812345678",
      "status": "completed",
      "end_reason": "completed",
      "duration_sec": 42,
      "campaign_id": 4821,
      "reference_id": "order-99213",
      "created_at": "2026-06-04T21:42:08+05:30"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 137,
    "total_pages": 3
  }
}

curl "https://voice.agentive.co.in/api/public/v1/calls?per_page=50&direction=outbound&status=completed" \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..."

{
  "status": "error",
  "code": 404,
  "details": "No recording is available for this call."
}

curl "https://voice.agentive.co.in/api/public/v1/calls/run_4821/recording" \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..." \
  --output call-4821.ogg

{
  "status": "success",
  "code": 200,
  "data": [
    { "id": 57, "name": "March promo", "type": "audio_blast", "status": "active" },
    { "id": 61, "name": "Renewal press-1", "type": "press1", "status": "active" },
    { "id": 72, "name": "Signup verification", "type": "otp", "status": "active" }
  ]
}

curl https://voice.agentive.co.in/api/public/v1/campaigns \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..."

{
  "status": "success",
  "code": 200,
  "data": {
    "balance_inr": 1842.5,
    "currency": "INR"
  }
}

curl https://voice.agentive.co.in/api/public/v1/account \
  -H "x-api-key: pk_live_..." \
  -H "x-api-secret: sk_live_..."

List calls returns a data array of call objects. The same shape appears in the call.* webhook events.

status and end_reason are closed sets. New values are not added without notice, so you can write exhaustive handling.

Send Indian mobile numbers in any of these forms; they are all normalised:

• 10-digit local: 9812345678
• With country code: 919812345678
• With plus prefix: +919812345678

reference_id is an optional string you attach to any request, such as an order number, ticket id, or signup id. It is:

• echoed back in the response reference_id field, and
• included in every webhook for the call or verification.

Use it to match our events back to your own records without storing our ids. Reference IDs are capped at 120 characters; control characters are stripped.

The call-placing endpoints (POST /calls and POST /otp/send) do not yet accept an idempotency key. If a request times out or the connection drops, the call may already have been placed, so a blind retry can result in a second call to the same number.

To make a retry safe:

• Send a unique reference_id on each request and record it on your side.
• Before retrying, check Get call status or List calls for that reference_id to see whether the call was already placed.
• For verification, remember that each /otp/send issues a fresh code; reuse the existing request_id rather than sending again if a code is already in flight.

1. 1
   Open the API tab in your dashboard and copy your publishable key and secret. Reveal the secret once and store it securely.
2. 2
   Pick or upload an audio clip in your audio library and note its id.
3. 3
   Place a test call:

   cURL

   Copy

   curl https://voice.agentive.co.in/api/public/v1/calls \
     -H "x-api-key: pk_live_..." \
     -H "x-api-secret: sk_live_..." \
     -H "Content-Type: application/json" \
     -d '{ "type": "audio_blast", "number": "98XXXXXXXX", "audio_id": 12, "reference_id": "test-1" }'

4. 4
   Note the unique_id and poll status:

   cURL

   Copy

   curl https://voice.agentive.co.in/api/public/v1/calls/run_XXXX \
     -H "x-api-key: pk_live_..." \
     -H "x-api-secret: sk_live_..."

5. 5
   To receive call results automatically instead of polling, set up a webhook.