Voice OTP API

The Voice OTP API places a phone call that reads a numeric one-time code out to your customer, then checks the code they type back into your app or website. Use it to verify a mobile number at signup, confirm a login or a payment, or as the fallback when an SMS code does not arrive.

Two requests cover the whole flow. POST /otp/send generates the code (or takes yours), places the call and returns a request_id. POST /otp/verify checks what the customer entered against that request and tells you whether it matched. Expiry, the attempt cap and single use are enforced on our side, and the plain code is never returned to you, never logged and never sent on a webhook.

Agentive ships two API families: the Voice APIs (Voice Broadcast, AI Voice Agent, Voice OTP and telephony webhooks) and the WhatsApp Business API. They share a brand, a dashboard account and a set of habits, but they are separate products and they do not agree on everything. This section is the one place that says what is common and, where they differ, exactly how.

Every path on this page is relative to the Voice API base URL. It is the same base the Voice Broadcast API uses, so one set of credentials covers both.

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

Verification endpoints use the same credentials as the rest of the Voice API: a publishable key and a secret, issued from the API tab in your Voice dashboard and sent as two request headers.

curl https://voice.agentive.co.in/api/public/v1/otp/send \
  -H "x-api-key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "x-api-secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "number": "9812345678" }'

The secret is shown in full exactly once, when it is generated or rotated, and is stored hashed on our side. If you lose it, rotate to get a new pair; the old secret stops working immediately. As an alternative to the two headers you may send the pair with HTTP Basic auth (the curl -u form, publishable key as the username and secret as the password), or put the secret in a secret field of the JSON body. When an x-api-key header is present it takes precedence.

curl https://voice.agentive.co.in/api/public/v1/otp/send \
  -u pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{ "number": "9812345678" }'

Authentication failures

The wording and the status are the same for an unknown key and a wrong secret, so credentials cannot be probed. 401 always means the credentials were rejected; 403 always means they were accepted and the account or the product is not entitled. Before September 2026 a known key with a wrong secret returned 403; move any branch that read 403 as "bad secret" to 401. Key rotation and the full credential model are covered in the Voice Broadcast API authentication section.

Every response is JSON and uses one consistent envelope.

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

Successful responses add endpoint-specific fields alongside the envelope: request_id, expires_in_sec, expires_at_ist and sometimes warnings on send; verified and verification_status on verify; and verification_status, call_status, verified, attempts, max_attempts and expires_at_ist on status. Error responses add error_code and error. Each is documented with its endpoint below.

Errors follow the envelope with status: "error", the HTTP status repeated in code, a stable machine string in error_code, and a human-readable details message (repeated in error). Branch on error_code; show details to your operators, not to your customers.

The split between 429 and 5xx matters for retry logic: a 429 means a limit was hit, so wait before retrying; a 5xx means a temporary problem on our side, so an immediate retry after a short pause is safe and, with the same Idempotency-Key, can never place a second call. Error responses never include internal infrastructure detail.

{
  "status": "error",
  "code": 400,
  "unique_id": null,
  "reference_id": "signup-7781",
  "details": "A valid Indian mobile number is required.",
  "error_code": "invalid_number",
  "error": "A valid Indian mobile number is required."
}

Verification is the highest-risk thing this API does, so it carries more limits than any other endpoint. Each one refuses with HTTP 429, names itself in error_code, and says how long to wait in both the Retry-After header and the body's retry_after_sec.

Standard rate-limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, plus X-RateLimit-* aliases of the same three values) are returned on responses so you can pace your requests. They describe the per-account bucket for that request's method: a GET reports the read bucket, a POST the write bucket.

{
  "status": "error",
  "code": 429,
  "unique_id": null,
  "reference_id": null,
  "details": "Too many requests. Please slow down and retry shortly.",
  "error": "Too many requests. Please slow down and retry shortly.",
  "error_code": "rate_limited",
  "retry_after_sec": 60
}

HTTP/1.1 429 Too Many Requests
Retry-After: 18

{
  "status": "error",
  "code": 429,
  "unique_id": null,
  "reference_id": "signup-7781",
  "details": "Too many verification calls to this number. Please wait a few moments before sending another.",
  "error": "Too many verification calls to this number. Please wait a few moments before sending another.",
  "error_code": "number_flood",
  "retry_after_sec": 18
}

HTTP/1.1 429 Too Many Requests
Retry-After: 2280

{
  "status": "error",
  "code": 429,
  "unique_id": null,
  "reference_id": "signup-7781",
  "details": "Too many incorrect codes for this number. It is locked for a short while.",
  "error": "Too many incorrect codes for this number. It is locked for a short while.",
  "error_code": "number_locked",
  "retry_after_sec": 2280
}

Responses to POST /otp/send also carry X-Agentive-Lines and X-Agentive-Lines-In-Use: how many calls your account can have live at once, and how many are live right now, whether the call was admitted or refused. Read endpoints do not send them. A send your account has no free line for is refused rather than queued, with HTTP 429, error_code: "concurrency_limit", lines, lines_in_use and retry_after_sec in the body and a Retry-After of 5 seconds, so you always know whether a code went out.

One verification request is described by the same set of fields wherever it appears: the extra fields on the send, verify and status responses, and the data object of every otp.* webhook, where data.object is "verification". The table notes where each field is present.

{
  "object": "verification",
  "request_id": "5f3c8b2a-1d4e-4a9c-9e7b-2c6f0a1b3d8e",
  "number": "+919812345678",
  "status": "failed",
  "verification_status": "pending",
  "verified": false,
  "attempts_left": 2,
  "max_attempts": 3,
  "campaign_id": 48213,
  "reference_id": "signup-7781"
}

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

{
  "status": "error",
  "code": 401,
  "details": "Incorrect code.",
  "error": "Incorrect code.",
  "error_code": "max_attempts",
  "verified": false,
  "attempts_left": 0,
  "verification_status": "locked"
}

{
  "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,
  "verification_status": "pending",
  "campaign_id": 48213,
  "warnings": ["weak_code"]
}

Register a webhook endpoint and every verification transition is pushed to you as a signed event, with data.object set to "verification" and your reference_id on the envelope. Four events cover the lifecycle.

Payload samples, the field-by-field verification object, signature verification, retries and event de-duplication are in the Telephony Webhooks reference.

Six identifiers move between your system and ours. Only one of them is the handle you poll and match on; the rest are for correlation, for fetching a specific artefact, or for retry safety.

The campaign decides, and only the campaign. You pick it once when you set the campaign up, and every code that campaign sends comes from what you picked. You cannot set it per request, and nothing overrides it or stands in for it later.

• If the campaign names one of your numbers, that number is used and the recipient sees your own line. Only your numbers enabled for voice broadcast can be picked.
• If the campaign names a rotational pool, the call goes out from a number in that pool, and the pool rotates across its numbers and paces them on your behalf.
• If what the campaign picked stops being usable— the number is switched off for broadcast, quarantined, or the pool is withdrawn — the request is refused with HTTP 400 telling you to open the campaign and pick again. Your codes are never quietly moved to some other number: you would not know it had happened, and neither would the customer seeing an unfamiliar caller.
• If your account has no broadcast number and no pool at all, the request is refused with HTTP 400 and "No number on your account is enabled for voice broadcast. Ask your account manager to enable one, then retry." Retrying will not help until a number is enabled.

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 a send or verify request, such as a signup id, a session id or an order number. It is echoed back in the response reference_id field and included on every webhook for the verification, so you can match our events to your own records without storing our ids.

Reference IDs are capped at 120 characters; control characters are stripped. A reference id never de-duplicates anything; use the Idempotency-Key header for retry safety.

Four endpoints accept an Idempotency-Key header: POST /otp/send and POST /otp/verify here, and POST /calls and POST /campaigns/:id/trigger in the Voice Broadcast API. Send a unique key with each logical request and a network retry can never place a second billed call, or spend a second verify attempt: if a request times out or the connection drops, resend the same request with the same key.

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

The key is 1 to 128 visible ASCII characters; a longer key is refused with HTTP 400 rather than cut short. Use something unique per action, such as a UUID or your signup id plus an attempt marker. Keys are scoped to your account and live for 24 hours.

A key is consumed only by a response that decided the request. Everything else releases it, so the same key is the right thing to retry with. The rule is identical on every Voice endpoint:

• Stored and replayed: 2xx, 400 (validation), the 401 that reports an incorrect code (because the attempt was already spent), 404, and 422. A stored 400 or 404 is replayed for the key's 24 hours even after you fix the request or the dashboard setting behind it, so send the fixed request with a new key.
• Not stored: 402 (balance), 403, 409 (still processing), 429 (any limit), and a 5xx raised before we asked the network to place the call. Once the condition clears, resend with the same key and the call is attempted.
• Stored, and it needs a decision from you: a 5xx raised after we asked the network to place the call. It is replayed as HTTP 502 with error_code: "call_state_unknown", because we cannot say whether the code went out. Poll Get verification status before you resend, or choose a fresh key deliberately.
• Replay markers: a replayed response carries both Idempotent-Replayed: true (the platform-wide name) and idempotency-replayed: true (the original one, kept so existing clients keep working).
• Same key, different body: HTTP 422 with error_code: "idempotency_conflict". A new request needs a new key.
• Key still in flight: HTTP 409 with error_code: "idempotency_in_progress" and Retry-After: 2, until the first request finishes. If our side restarts mid-request the key is released at once.

From a new key to a verified number, using your own phone as the recipient.

1. 1
   Create your authentication campaign

   In your Voice dashboard, create a campaign of type Authentication. It holds everything about how the call is made: how many digits the code has, how long it stays valid, what is spoken, and which of your numbers (or which rotational pool) the recipient sees. Sending is refused until this exists, because there would be nothing to read out and no number to call from.
2. 2
   Get your keys

   Open the API tab in your Voice dashboard and copy the publishable key and secret. The secret is revealed once; store it in your server's environment, never in client code.
3. 3
   Send a code to your own number

   Replace 98XXXXXXXX with your mobile number. Note the request_id in the response.

   cURL

   Copy

   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": "98XXXXXXXX", "reference_id": "test-1" }'

4. 4
   Answer the call

   Your phone rings within moments. The code is read digit by digit, then repeated. Write it down.
5. 5
   Verify the code

   Send the code back with the request_id. A correct code returns verified: true; a wrong one returns HTTP 401 with attempts_left, so try a wrong code first to see both.

   cURL

   Copy

   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": "REQUEST_ID_FROM_SEND", "code": "CODE_YOU_HEARD" }'

6. 6
   Check the request, or subscribe to events

   Read the request's state at any time, or register a webhook to have otp.sent, otp.verified, otp.failed and otp.max_attempts pushed to you.

   cURL

   Copy

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

A send-then-verify pair you can drop into a signup or login handler. Call sendOtp when the customer submits their number and keep the returned request_id with their session; call verifyOtp with the code they type. A return of true means verified; anything else is the message to show them.

# 1. Send the code. Note request_id from the response.
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", "reference_id": "signup-7781" }'

# 2. Verify what the customer typed.
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": "204815" }'

The other references share this base URL, envelope and credentials.