Phone Verification

Verify phone numbers via OTP delivered through SMS or WhatsApp. OTPs expire after 10 minutes and allow up to 3 retry attempts.

Supported Channels

OTPs can be delivered via sms (default) or whatsapp, matching the VerifyHQ API DTO.

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 whatsapp

Code Examples

curl -X POST https://api.verifyhq.wejoona.com/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/verify

Submit the verification ID and OTP code received by the user.

Request Body

Parameter	Type	Description
`verificationId`required	string	Verification ID returned by POST /verifications/phone
`code`required	string	The 6-digit OTP code

curl -X POST https://api.verifyhq.wejoona.com/verifications/phone/verify \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "verificationId": "pv_abc123", "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.wejoona.com/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)