Phone Verification

Phone verification confirms that an account holder controls the phone number associated with their account. Two signals combine to produce the result:

  1. A one-time passcode sent via SMS — the standard "we sent you a code, enter it here" interaction that proves the user has the device.
  2. Passive mobile-identity signals — carrier information, trust scores, and behavioral characteristics that Frame's verification partner evaluates in the background.

If both signals look good, verification passes with minimal friction. If the passive signals flag risk, Frame adds additional steps. The point is to keep legitimate users moving fast and concentrate friction where the data says there's actual risk.

Once verified, the phone number becomes the account holder's identity anchor inside Frame — used to cross-reference against KYC data, to re-authenticate sensitive actions, and to keep an audit trail of who's controlling the account.

When to use it

Request phone_verification when:

  • You want a lightweight first check before a full KYC investment — phone verification catches a meaningful chunk of bad-actor signups before you spend KYC document-review budget on them.
  • You need re-authentication for sensitive actions (updating payout details, changing identity info, large transactions) without putting the account holder through full KYC again.
  • You want a cross-reference signal that pairs with KYC: phone-confirmed identity matches against the same fields submitted during KYC, strengthening the overall verification confidence.

The phone number on the account holder's profile is the input — the number you'd want to verify is profile.individual.phone.

How it works

When phone_verification is pending on an account and the onboarding session runs:

  1. Frame looks up the phone number through its verification partner. Carrier, trust score, behavioral signals — all evaluated in the background.
  2. Frame sends an OTP via SMS to the number on file.
  3. The account holder enters the OTP inside the onboarding session.
  4. Frame validates the OTP and combines it with the background signals.
    • Good OTP + good passive signals → capability activates.
    • Good OTP + flagged passive signals → additional steps prompted (or flagged for review).
    • Bad OTP → retry up to a limit, then capability transitions to disabled.

If you're using the hosted onboarding session, Frame handles the entire SMS round-trip — sending, retries, validation. If you're driving the flow yourself (custom UI without a session), the OTP endpoints are exposed for direct integration.

Pairing with KYC

Phone verification is meaningfully better when paired with KYC. Frame cross-references the identity signals tied to the phone number against the name, address, and DOB submitted during KYC — a mismatch (verified phone belongs to "Jane Doe" but KYC submitted for "John Smith") is a strong fraud signal. The combined posture is stronger than either capability alone:

  • phone_verification alone — confirms the user controls the device.
  • phone_verification + kyc — confirms the user controls the device and the device is associated with the identity they're claiming.

Most production flows combine them. Standalone phone_verification is for cases where you don't need full KYC but want at least a thin identity anchor.

Re-authentication

Once a phone number is verified, it can be reused for re-authentication on sensitive actions without forcing a full KYC re-run:

  • Updating payout details — re-verify the phone before accepting the new bank account.
  • Changing identity fields — re-verify before the change lands.
  • High-value transactions — step-up auth via the same OTP flow.

The re-auth path is the same primitive: OTP delivery + validation. The capability stays active between events; you trigger fresh OTPs on demand.

OTP endpoints (custom UI alternative)

If you're not using the hosted onboarding session — for example, building your own verification UX — Frame exposes the OTP flow as direct endpoints on the account:

  • POST /v1/accounts/:account_id/phone_verifications — send an OTP to the account's phone number.
  • POST /v1/accounts/:account_id/phone_verifications/:id/confirm — confirm the OTP and activate the capability.

The trade-off: you handle UX (input fields, error messages, retry logic), Frame handles delivery and validation. Use the hosted session for the standard case; reach for direct endpoints when your UX requirements demand it.

What it doesn't do

Phone verification confirms control of a number at the moment of verification. It doesn't:

  • Continuously monitor the number for SIM swaps or porting events.
  • Guarantee the number won't change hands later — re-verify on sensitive actions if that matters.
  • Verify the identity of the person behind the number — that's KYC's job.
  • Replace 2FA or platform-level authentication — phone verification is an identity signal, not a session authenticator for your application.

Gotchas

Symptom: the account holder isn't receiving the OTP SMS. Why: common causes — number formatting issues, carrier filtering, the user's phone is off-network, the verification partner's deliverability is degraded. Fix: confirm the number on the profile matches the format Frame expects (number + country_code as separate fields, no formatting characters); if delivery is consistently failing across users, contact Frame support — there may be a partner-side issue.

Symptom: you requested kyc_prefill and got back capabilities that include phone_verification you didn't ask for. Why: kyc_prefill depends on phone_verification — when you request prefill, Frame automatically expands the request to include phone verification, because the prefill lookup is anchored on a verified phone number. The dependency runs in this direction; verifying a phone alone does not satisfy KYC Prefill. Fix: this is expected behavior — phone verification is part of how KYC Prefill works.

Symptom: a verified phone number on one account shows up flagged on another account. Why: the same number being used across multiple accounts is itself a signal — Frame's evaluation factors number reuse into the trust score. Fix: not necessarily a bug; could be a legitimate household sharing a number, could be a fraud signal. Use it as one input to your platform's account-relationship policy.

Reference

For onboarding session creation (where phone verification flows live), see POST/v1/onboarding_sessions.