Skip to main content
The Verify API handles the complete OTP lifecycle: it sends a 6-digit code to a phone number via SMS, verifies the code your user enters, and optionally generates a cryptographic HMAC proof that lets your backend confirm the validation offline — without making an additional authenticated API call.

​
Base URL

​
Authentication

All endpoints require your API key in the X-API-Key request header.
Exception: POST /v1/verify-proof does not require authentication. The HMAC proof itself serves as the credential.

​
How it works

  1. POST /v1/validations — Submit the phone number. The API sends a 6-digit code via SMS and returns a token you use in subsequent calls.
  2. User receives SMS — Your user reads the 6-digit code from their phone.
  3. POST /v1/validations//verify — Submit the code the user entered. On success, you receive the verified phone number and an optional HMAC proof.
  4. Verify HMAC proof (optional) — Pass the proof and associated fields to POST /v1/verify-proof (no auth required) or PATCH /v1/validations/{token} to confirm the validation is authentic on your backend.

​
Validation statuses

Each validation session moves through the following statuses:

​
HMAC offline proof

When your account has a verificationSecret configured, every validation response includes a proof field containing an HMAC signature computed from the phone number, token, code, and timestamp. You can pass these four fields plus the proof to POST /v1/verify-proof — which requires no authentication — to confirm that a verification was genuinely completed. This is useful for microservices, edge functions, or any backend that should not hold your API key.

​
Rate limiting

The API applies two levels of rate limiting:
  • Per account (tenant) — a cap on total validations across all phone numbers on your account.
  • Per phone number — a cap on how many times a single number can be validated in a rolling window.
Requests that exceed either limit receive a 429 response with an error code of TENANT_RATE_LIMIT or PHONE_RATE_LIMIT.

​
Endpoints summary

Individual endpoints — with parameters, request bodies, and examples — are listed in this section’s sidebar, generated directly from the OpenAPI specification.