Phone Verification

Verify phone numbers via OTP (SMS or voice call). Supports all African mobile networks including MTN, Airtel, Orange, Safaricom, and more. OTPs expire after 10 minutes and allow up to 3 retry attempts.

Supported Channels

OTPs can be delivered via SMS (default) or voice call. Voice is recommended for landlines or regions with unreliable SMS delivery.

POST/verifications/phone

Initiate a phone verification by sending an OTP to the specified number.

Request Body

Parameter	Type	Description
`phoneNumber`required	string	Phone number in E.164 format (e.g. +2250700000000)
`userId`required	string	Your internal user identifier
`channel`	enum	Delivery channel: SMS (default) or VOICE
`locale`	string	Locale for the OTP message (e.g. fr, en). Default: en

Code Examples

curl -X POST https://api.verifyhq.com/v1/verifications/phone \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+2250700000000",
    "userId": "user_123",
    "channel": "SMS"
  }'

Response

201 Createdjson

{
  "id": "pv_abc123",
  "userId": "user_123",
  "phoneNumber": "+2250700000000",
  "channel": "SMS",
  "status": "PENDING",
  "expiresAt": "2026-02-18T13:10:00Z",
  "createdAt": "2026-02-18T13:00:00Z"
}

POST/verifications/phone/:id/verify

Submit the OTP code received by the user to complete verification.

Request Body

Parameter	Type	Description
`code`required	string	The 6-digit OTP code

curl -X POST https://api.verifyhq.com/v1/verifications/phone/pv_abc123/verify \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482910" }'

Response

200 OKjson

{
  "id": "pv_abc123",
  "status": "VERIFIED",
  "phoneNumber": "+2250700000000",
  "verifiedAt": "2026-02-18T13:02:15Z"
}

GET/verifications/phone/:id

Retrieve the current status of a phone verification.

curl https://api.verifyhq.com/v1/verifications/phone/pv_abc123 \
  -H "X-API-Key: your_api_key"

Response

200 OKjson

{
  "id": "pv_abc123",
  "userId": "user_123",
  "phoneNumber": "+2250700000000",
  "channel": "SMS",
  "status": "VERIFIED",
  "attemptsRemaining": 2,
  "expiresAt": "2026-02-18T13:10:00Z",
  "verifiedAt": "2026-02-18T13:02:15Z",
  "createdAt": "2026-02-18T13:00:00Z"
}

Verification Statuses

Parameter	Type	Description
`PENDING`	status	OTP sent, awaiting user submission
`VERIFIED`	status	OTP matched successfully
`FAILED`	status	Max attempts exceeded or invalid code
`EXPIRED`	status	OTP expired (10-minute window)

Webhook Events

Parameter	Type	Description
`phone.verified`	event	Phone number successfully verified
`phone.failed`	event	Phone verification failed (max attempts or expired)