Phone Verifications

Initiates a phone verification for the given account by sending a one-time passcode (OTP) via SMS to the account's phone number. frameOS evaluates mobile identity signals in the background — including the number's trust score, carrier information, and behavioral characteristics — to determine whether the user presents a risk.

If you are using onboarding sessions, frameOS handles the full OTP flow — sending, delivery, and validation — with no additional integration required. Call this endpoint directly only when managing the verification flow outside of an onboarding session.

Create phone verification

Initiates a phone verification for the given account by sending a one-time passcode (OTP) via SMS to the account's phone number. frameOS evaluates mobile identity signals in the background — including the number's trust score, carrier information, and behavioral characteristics — to determine whether the user presents a risk.

If you are using onboarding sessions, frameOS handles the full OTP flow — sending, delivery, and validation — with no additional integration required. Call this endpoint directly only when managing the verification flow outside of an onboarding session.

Path parameters
account_idstringrequired

The ID of the account to initiate phone verification for.

Body parameters
typestringoptional

Verification type (e.g. twilio, prove)

phone_numberstringoptional

The phone number to verify. This is the number that will receive the OTP and be linked to the account holder's identity within Frame.

date_of_birthstringoptional

Date of birth (saved to account profile if provided)

Returns

Phone verification created and OTP sent to the account's phone number.

POST/v1/accounts/{account_id}/phone_verifications
curl --request POST \
  --url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phone_verifications \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "1dc265a7-bc64-4c81-9713-b2f21787a9ab",
  "type": "phone",
  "status": "pending",
  "provider": "sandbox",
  "sandbox": {
    "expected_codes": [
      "123456",
      "000000",
      "111111"
    ]
  }
}

Confirm phone verification

Confirms a phone verification by validating the OTP code sent to the account's phone number. If the code is correct and has not expired, the phone number is linked to the account holder's identity within Frame and the verification status transitions to verified.

If the number passes verification, the account holder is authenticated and their phone number is linked to their identity. If the number shows suspicious characteristics, additional verification steps may be introduced or the evaluation may be flagged for review.

Path parameters
account_idstringrequired

The ID of the account the phone verification belongs to.

idstringrequired

The ID of the phone verification to confirm.

Body parameters
codestringoptional

The one-time passcode (OTP) sent via SMS to the account holder's phone number.

Returns

Phone verification confirmed. The phone number is now linked to the account holder's identity and the verification status is verified.

POST/v1/accounts/{account_id}/phone_verifications/{id}/confirm
curl --request POST \
  --url https://api.framepayments.com/v1/accounts/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phone_verifications/a70cd72f-e74a-40f2-96a2-3f60714aac4a/confirm \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "7dd32380-7411-455f-ad62-397148b1279b",
  "status": "verified",
  "provider": "twilio"
}