Phone Verification
Phone verification confirms that an account holder owns and controls the phone number associated with their account. frameOS uses mobile identity signals to distinguish real users from those exhibiting suspicious behavior — applying additional friction only where there's actual risk, without slowing down legitimate users.
When enabled, the account holder's phone number becomes their primary identifier within Frame, and is used to perform associated lookups against their KYC data to confirm they are who they say they are.
If you're using KYC Prefill, phone verification happens automatically as part of the prefill lookup. You don't need to add any additional steps.
How it works
When an account has the phone_verification capability, frameOS looks up the provided phone number and evaluates a set of mobile identity signals in the background. This includes assessing the number's trust score, carrier information, and behavioral characteristics to determine whether the user presents a risk.
As part of the verification flow, the account holder receives a one-time passcode (OTP) via SMS to confirm they control the number. If you're using onboarding sessions, frameOS handles the full OTP flow — sending, delivery, and validation — with no additional integration required on your end.
If the number passes verification, the account holder is authenticated and their phone number is linked to their identity within Frame. If the number shows suspicious characteristics, additional verification steps are introduced — or the evaluation is flagged for review.
Use cases
Identity confirmation during onboarding
Phone verification is a lightweight first check before an account holder completes full KYC. Confirming control of a phone number early in the onboarding flow establishes a trusted identity anchor and catches bad actors before they progress further.
Fraud prevention for high-risk transactions
For platforms where users initiate large payouts, withdrawals, or other sensitive actions, phone verification adds a layer of assurance that the person initiating the action is the verified account holder — not a bad actor who has compromised an account.
Re-authentication for returning users
When a returning user accesses a sensitive part of your platform — such as updating their payout details or changing their identity information — phone verification can be used to re-confirm their identity without requiring them to go through full KYC again.
Marketplace and platform onboarding
For platforms onboarding large volumes of end users, phone verification provides a scalable way to filter out suspicious sign-ups before they reach the rest of your onboarding flow. Users who pass move forward seamlessly; those who don't can be prompted for additional verification.
Relationship to KYC
Phone verification and KYC work together. When both capabilities are requested, the phone number is used to anchor the account holder's identity and cross-reference their KYC data. This means that the name, address, and other identity information submitted during KYC is validated against the identity signals tied to the phone number — adding a stronger layer of confidence to the overall verification result.
If you're using KYC Prefill, this cross-referencing happens automatically as part of the prefill flow.
Create an account with phone verification
Add phone_verification to the capabilities array when creating the account. The account holder's phone number is required.
Parameters
Must be individual. Phone verification is only supported for individual accounts.
Include phone_verification to enable phone-based identity verification. Combine with kyc or kyc_prefill for a full identity verification flow.
Object containing number and country_code for the account holder's phone. This is the number that will be verified and used as their identity anchor within Frame.
The account holder's email address.
The account holder's first name.
The account holder's last name.
curl --request POST \
--url https://api.framepayments.com/v1/accounts \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"type": "individual",
"capabilities": ["phone_verification", "kyc"],
"profile": {
"individual": {
"email": "marcia@example.com",
"name": {
"first_name": "Marcia",
"last_name": "Longo"
},
"phone": {
"number": "3107484186",
"country_code": "1"
}
}
}
}'
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"object": "account",
"type": "individual",
"status": "pending",
"external_id": null,
"capabilities": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
"object": "capability",
"name": "phone_verification",
"status": "pending",
"disabled_reason": null,
"currently_due": [],
"disabled": null
},
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
"object": "capability",
"name": "kyc",
"status": "pending",
"disabled_reason": null,
"currently_due": [],
"disabled": null
}
],
"profile": {
"individual": {
"email": "marcia@example.com",
"ssn_last_four": null,
"name": {
"first_name": "Marcia",
"middle_name": null,
"last_name": "Longo",
"suffix": null
},
"phone": {
"number": "3107484186",
"country_code": "1"
},
"birthdate": null,
"address": null
}
},
"terms_of_service": null,
"metadata": {},
"livemode": false,
"created": 1721010605
}
Complete onboarding
Once the account is created, create an onboarding session to run the phone verification flow. frameOS evaluates the phone number in the background and guides the account holder through any additional steps required.
curl --request POST \
--url https://api.framepayments.com/v1/onboarding_sessions \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"return_url": "https://example.com/onboarding/complete"
}'
After the session completes, retrieve the account to check the phone_verification capability status. A status of active means the phone number was successfully verified and linked to the account holder's identity.