Voice calls and verification
Confirm that someone owns a phone number by calling it and reading out a code. Let us manage the code, or bring your own.
Which one to use
| Verify | Calls | |
|---|---|---|
| Who makes the code | We generate a 6 digit code. | You do. |
| Who checks it | We do, with POST /v1/verify/check. | You do. |
| Charged | One verification, up front. | Per call, up front. |
| Use it when | You want the simplest working flow. | You already have your own code logic. |
Verify a phone number
1. Start a verification
POST /v1/verify/start charges one verification, generates a 6 digit code, calls the number and reads the code out. channel is optional; voice is the only channel.
curl https://api.kpododo.com/v1/verify/start \
-H "Authorization: Bearer $KPODODO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"to": "+233244000111", "channel": "voice"}'{ "request_id": "vr_...", "status": "pending", "to": "•••0111", "channel": "voice" }2. Check the code
Send the code the user typed, with the request_id from step 1.
curl https://api.kpododo.com/v1/verify/check \
-H "Authorization: Bearer $KPODODO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"request_id": "vr_...", "code": "123456"}'{ "request_id": "vr_...", "status": "approved" }statusisapprovedordenied.- A code expires after 10 minutes and allows 5 checks. A wrong code, an expired request or one with no checks left returns
denied. - Once a request is approved, checking it again returns
denied. Mark the number as verified on your side the first time you seeapproved. - An unknown
request_id, or one from another account, returns 404NOT_FOUND.
Verification webhooks
If you have a webhook endpoint, verify.delivered tells you the call carrying the code was answered, and verify.failed that it ended without being answered, so you can offer the user another try. The data holds call_id, request_id, the masked to, status, hangup_cause and billable_seconds. One verification can send verify.delivered twice (when the call is answered, and again when it ends), so act on it once per request_id.
Place a call with your own code
POST /v1/calls calls the number and reads out the digits you pass in say.digits. The digits are spoken and never stored or logged, so you keep the code and check what the user types yourself. Each call is charged up front.
curl https://api.kpododo.com/v1/calls \
-H "Authorization: Bearer $KPODODO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"to": "+233244000111", "say": {"digits": "482913"}}'{ "call_id": "call_...", "status": "queued", "to": "•••0111", "created_at": "..." }Follow the call
GET /v1/calls/{call_id} returns the same shape with the current status and a hangup_cause.
curl https://api.kpododo.com/v1/calls/call_... \
-H "Authorization: Bearer $KPODODO_API_KEY"| Status | Meaning |
|---|---|
queued | Accepted, not yet ringing. |
in_progress | The call is under way. |
answered | The call was answered. |
busy | The line was busy. |
no_answer | Nobody answered. |
failed | The call could not be completed. |
hangup_cause is the raw telephony cause, such as NORMAL_CLEARING or USER_BUSY. With a webhook endpoint you also receive call.ringing, call.answered and call.completed. See event types.