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

VerifyCalls
Who makes the codeWe generate a 6 digit code.You do.
Who checks itWe do, with POST /v1/verify/check.You do.
ChargedOne verification, up front.Per call, up front.
Use it whenYou 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"}'
Response
{ "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"}'
Response
{ "request_id": "vr_...", "status": "approved" }
  • status is approved or denied.
  • 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 see approved.
  • An unknown request_id, or one from another account, returns 404 NOT_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"}}'
Response
{ "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
curl https://api.kpododo.com/v1/calls/call_... \
  -H "Authorization: Bearer $KPODODO_API_KEY"
StatusMeaning
queuedAccepted, not yet ringing.
in_progressThe call is under way.
answeredThe call was answered.
busyThe line was busy.
no_answerNobody answered.
failedThe 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.