Initiate Verification

Begin verifying a phone number. TryVox generates a 6-digit OTP and delivers it to the number via voice call (default) or SMS. The number is recorded as pending until the OTP is submitted via Submit OTP.

Endpoint

POST https://api.tryvox.io/v1/voice/accounts/{auth_id}/verified-caller-ids

Request body

Example request

curl -X POST https://api.tryvox.io/v1/voice/accounts/$TRYVOX_AUTH_ID/verified-caller-ids \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "alias": "Office line",
    "channel": "call"
  }'

Response

201 Created:

{
  "id": "8f7a4b2e-91c2-4f3d-9a1e-2c4b6d8f0a1c",
  "phone_number": "+919876543210",
  "verification_status": "pending",
  "message": "Verification code sent via call to +919876543210"
}

Response fields

• id — UUID of the caller ID record. Use it as a stable handle in your own systems.
• phone_number — the number being verified, echoed back.
• verification_status — always pending on first initiation.
• message — human-readable confirmation of the delivery channel.

Behavior

• Re-initiation while pending: allowed. Submitting a new request for the same phone_number resets the OTP to a fresh value. The old OTP becomes invalid.
• Already verified: if the number is already verified on this account, the API returns 409 ALREADY_VERIFIED instead of issuing a new OTP. Delete the entry first if you want to re-verify.
• OTP delivery latency: voice OTPs typically arrive within 5–10 seconds; SMS within 30 seconds depending on carrier.
• OTP lifetime: valid until a new initiation is requested for the same number.

Errors

Next step

Submit the OTP →