Guides

Phone verification

Send a one-time code to a user's phone number and check it, in the sandbox and in live.

A user is created with an unverified phone number in live. Two routes let you verify it with a one-time code sent by WhatsApp, with an automatic fallback to SMS:

Send a verification code, POST /v1/users/{id}/verification
Check the verification code, POST /v1/users/{id}/verification/check

On success the user's verified field becomes true. No event is emitted for it: read the user to see the result.

# 1. Send the code
curl -X POST "https://sdk.tilt-pay.com/v1/users/4821/verification" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY"

# 2. Check what the user typed
curl -X POST "https://sdk.tilt-pay.com/v1/users/4821/verification/check" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

The first call returns a verification object with status: "pending", expires_at and resend_available_at. Once the code is accepted the check returns status: "approved".

Sandbox#

Nothing is sent. The code is always 123456, there is no resend delay, and the hourly limits are ten times higher. Users created with a sandbox key are already verified, so you only need these routes to test your flow end to end: create a user, then send and check the code.

Live#

Note Live phone verification is switched on per platform by Tilt Pay. When it is not enabled, calls made with a live key answer 403 live_feature_unavailable. Check that your organization has live access first (see Going live).

A code is valid for 10 minutes and is invalidated after 5 incorrect attempts. Sending a new code replaces any pending one.
Limits: 60 seconds between two codes for the same user, 5 codes per user per hour, 20 per IP address per hour and 300 per project per hour. Above them you get 429 rate_limit_exceeded with a Retry-After header.
The code is 4 to 10 digits. Your user types it in your app: never display it from the API (it is never returned).
The answers never reveal whether a number exists elsewhere.

Errors#

Status	Code	Meaning and what to do
409	`already_verified`	The number is already verified (live). Nothing to do.
409	`no_pending_verification`	No code is pending: send one first.
409	`user_suspended`	The user is suspended.
422	`invalid_verification_code`	Wrong code. The message tells how many attempts remain; `param` is `code`.
422	`verification_expired`	The code is older than 10 minutes: send a new one.
422	`verification_attempts_exceeded`	5 wrong attempts: send a new code.
429	`rate_limit_exceeded`	Resend delay or hourly limit: wait for `Retry-After` seconds.
403	`live_feature_unavailable`	Live verification is not enabled for the platform.
503	`verification_unavailable`	The messaging service is unavailable. Retry shortly: a failed check does not use an attempt.

Both routes accept an Idempotency-Key. See Errors for the full list of codes.