Verification Methods
All verification sessions expire 10 minutes after creation. If the user doesn’t complete verification within that window, you’ll need to create a new session. Design your UX to guide users through verification promptly and handle the expired session error gracefully. See Errors & Edge Cases for details. Choosing Your Phone Verification Method
Phone verification is handled entirely within the Opal embedded UI. The user enters their phone number, receives a verification code, and enters it — all within a polished, pre-built interface. This is the fastest path to implementation and provides the most consistent user experience.
Method sends a verification code to the user’s phone, and your application collects and submits the code. Choose this if you want to integrate phone verification into your own custom UI while still having Method handle the SMS delivery.# 1. Create SMS verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
-H "Authorization: Bearer sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"type": "phone",
"method": "sms",
"sms": {}
}'
# 2. Submit the code the user received
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
-H "Authorization: Bearer sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"type": "phone",
"method": "sms",
"sms": {
"sms_code": "123456"
}
}'
The phone is verified in the background using carrier-level network signals, with no user interaction required. This provides the best user experience (the user doesn’t have to do anything), but availability depends on the user’s carrier and network conditions. Consider SNA as a primary method with SMS as a fallback.SNA requires the user to be on a mobile device connected to a supported carrier’s network. It does not work on landlines, VoIP numbers, or most prepaid/MVNO carriers. The returned URLs must be opened via background request or the device’s mobile browser. Always implement SMS as a fallback — SNA failures may be silent and your application needs to detect them (via session status polling or webhook) and offer an alternative. SNA access attempts are limited to 5 per session before the session fails.
You handle SMS delivery and verification entirely on your side and report the result to Method. Choose this if you already have a robust SMS verification system and want to maintain a single verification flow across your application.BYO SMS requires your team to be pre-authorized during onboarding. You’ll create a verification session with method byo_sms and provide the byo_sms.timestamp field — the ISO 8601 timestamp of when you verified the phone number. Contact your Method CSM to enable this method.
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
-H "Authorization: Bearer sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"type": "phone",
"method": "byo_sms",
"byo_sms": {
"timestamp": "2026-04-10T12:00:00.000Z"
}
}'
Choosing a Phone Method
| Method | User Experience | Implementation | Reliability | Best For |
|---|
| Opal | Polished, pre-built | Minimal (embed SDK) | High | Most teams |
| SMS | Standard (enter code) | Medium (collect + submit) | High | Custom UI with Method SMS delivery |
| SNA | Invisible (no user action) | Medium (background URL calls) | Variable (carrier-dependent) | Mobile-first products, with SMS fallback |
| BYO SMS | Your existing flow | Low (report result) | Depends on your provider | Teams with existing SMS verification |
Phone verification has a maximum attempt limit enforced by the underlying SMS provider. If the limit is reached, the error ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS is returned and you’ll need to wait before retrying. Design your flow to inform users of the limit and avoid excessive retries.
Choosing Your Identity Verification Method
Opal (Recommended)
KBA
BYO KYC
Identity verification is handled within the Opal embedded UI. The user is guided through the KYC process in a managed, tested flow. This is the simplest path and ensures the verification experience is optimized for completion.
The user answers a set of identity questions generated from their credit and public record history (e.g., “Which of these addresses have you lived at?”). Your application presents the questions and collects answers. KBA is widely supported but can be frustrating for users if questions are obscure or ambiguous.# 1. Create KBA verification session (returns questions)
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
-H "Authorization: Bearer sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"type": "identity",
"method": "kba",
"kba": {}
}'
# 2. Submit answers to the questions
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
-H "Authorization: Bearer sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"type": "identity",
"method": "kba",
"kba": {
"answers": [
{ "question_id": "qtn_xxx", "answer_id": "ans_xxx" },
{ "question_id": "qtn_yyy", "answer_id": "ans_yyy" }
]
}
}'
You perform identity verification on your side using your own KYC provider and report the outcome to Method. Choose this if you already have a KYC integration and want to consolidate verification into a single flow, or if you need to meet specific compliance requirements that require a particular KYC vendor.BYO KYC requires your team to be pre-authorized during onboarding. By creating this session, you’re asserting that your external KYC process has passed for this user. Method trusts your KYC result — there are no constraints on which KYC vendor you use. Contact your Method CSM to enable this method.
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
-H "Authorization: Bearer sk_xxx" \
-H "Content-Type: application/json" \
-d '{
"type": "identity",
"method": "byo_kyc",
"byo_kyc": {}
}'
byo_kyc: { authenticated: true } confirming the verification was recorded. Choosing an Identity Method
| Method | User Experience | Implementation | Best For |
|---|
| Opal | Guided, pre-built | Minimal | Most teams |
| KBA | Multi-question quiz | Medium (present questions, collect answers) | API-only integrations without existing KYC |
| BYO KYC | Your existing flow | Low (report result) | Teams with existing KYC provider |
About element and method_verified methods: The API also lists element and method_verified as valid verification methods. element is the predecessor to Opal — new integrations should use Opal instead. method_verified is an internal method used by Method and is not available for external use.
