Signup Phone Verifications

Send or verify a phone verification code

post

Two-step phone verification for signup. - Send code: provide phoneNumber (and optionally recaptchaToken, language). Provider (Firebase or Twilio) is determined by tenant configuration. - Verify code: provide sessionId and verificationCode from the previous step. Mobile clients using the Firebase SDK directly can provide verificationId + phoneNumber + verificationCode instead of a sessionId.

Body

phoneNumberstringOptional

Phone number in E.164 format (e.g., [phone])

Example: [phone]

recaptchaTokenstringOptional

reCAPTCHA token from Firebase. Required when the tenant is configured to use Firebase phone verification.

languagestringOptional

Preferred language for SMS message

Example: en-US

verificationIdstringWrite-onlyOptional

Firebase verification ID from the native mobile SDK. Used only for the verify step — mobile clients that use Firebase SDK directly provide this instead of a sessionId.

sessionIdstringOptional

Session ID returned from the initial request. Required when submitting a verification code.

Example: pv_123e4567-e89b-12d3-a456-426614174000

verificationCodestringOptional

6-digit verification code. When present, the endpoint verifies the code instead of sending a new one.

Example: 123456

Responses

201

Returns the verification session

application/json

sessionIdstringRead-onlyRequired

Session ID for tracking verification

Example: pv_123e4567-e89b-12d3-a456-426614174000

phonePreviewstringRead-onlyRequired

Phone number preview (last 4 digits)

Example: 1234

statusstring · enumRead-onlyRequired

Session status

Possible values:

expiresAtstring · date-timeRead-onlyRequired

Session expiration timestamp

remainingAttemptsnumberRead-onlyRequired

Remaining verification attempts

422

Validation error (invalid phone, denied number, reCAPTCHA error, invalid/expired session, invalid code, max attempts exceeded, etc.)

429

Too many requests

post/signup/phone-verifications

POST /apis/v2/signup/phone-verifications HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "phoneNumber": "[phone]",
  "recaptchaToken": "text",
  "language": "en-US",
  "verificationId": "text",
  "sessionId": "pv_123e4567-e89b-12d3-a456-426614174000",
  "verificationCode": "123456"
}

{
  "sessionId": "pv_123e4567-e89b-12d3-a456-426614174000",
  "phonePreview": "1234",
  "status": "pending",
  "expiresAt": "2026-01-01T00:00:00.000Z",
  "remainingAttempts": 1,
  "errors": [
    {
      "code": "text",
      "message": "text",
      "details": {}
    }
  ]
}