The prefill flow allows users to automatically populate their KYC information using their phone number. This significantly reduces manual data entry and improves the user experience.
How It Works
- User provides their phone number and date of birth
- System sends an OTP (One-Time Password) to the phone
- User enters the OTP to verify phone ownership
- System returns prefilled user data (name, address, SSN last 4, etc.)
- User reviews and submits for verification via
/v1/kyc/start
Step 1: Start Prefill
Initiate the prefill process with the user’s phone number and date of birth.
Request
{
"phoneNumber": "+15551234567",
"dateOfBirth": "1990-01-15",
"userId": "user_123",
"sessionToken": "session_abc",
"ipAddress": "192.168.1.1"
}
Request Fields
| Field | Type | Required | Description |
|---|
phoneNumber | string | Yes | User’s phone number with country code |
dateOfBirth | string | Yes | Date of birth (YYYY-MM-DD format) |
userId | string | Yes | Your internal user identifier |
sessionToken | string | Yes | Session token for the request |
ipAddress | string | No | User’s IP address for fraud detection |
Response
{
"status": {
"decision": "pending",
"status": "otp_sent",
"subStatus": "",
"externalId": "ext_abc123"
},
"externalId": "ext_abc123"
}
Step 2: Submit OTP
After the user receives the OTP on their phone, submit it for verification.
Request
{
"otp": "123456",
"externalId": "ext_abc123"
}
Request Fields
| Field | Type | Required | Description |
|---|
otp | string | Yes | The 6-digit OTP received by the user |
externalId | string | Yes | External ID from the prefill response |
Response
On successful OTP verification, the response includes prefilled user data:
{
"status": {
"decision": "pending",
"status": "prefill_complete",
"subStatus": "",
"externalId": "ext_abc123"
},
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"dateOfBirth": "1990-01-15",
"phoneNumber": "+15551234567",
"email": "john.doe@example.com",
"ssn": "1234",
"address": {
"addressLine1": "123 Main Street",
"addressLine2": "Apt 4B",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "US"
}
}
Prefill Response Fields
| Field | Type | Description |
|---|
firstName | string | User’s first name |
middleName | string | User’s middle name (if available) |
lastName | string | User’s last name |
dateOfBirth | string | Date of birth |
phoneNumber | string | Verified phone number |
email | string | Email address (if available) |
ssn | string | Last 4 digits of SSN |
address | object | Address information |
All fields except status are optional and may be null if data is not available from the prefill provider.
Step 3: Submit to KYC Verification
After receiving prefill data, use it to start the full verification process. The prefill response fields map directly to the /v1/kyc/start request.
Mapping Prefill Data to Verification Request
{
"userId": "user_123",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"email": "john.doe@example.com",
"phoneNumber": "+15551234567",
"dateOfBirth": "1990-01-15",
"ssn": "123-45-6789",
"address": {
"addressLine1": "123 Main Street",
"addressLine2": "Apt 4B",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "US"
},
"sessionToken": "session_abc",
"agreementTime": "2024-01-15T10:30:00Z",
"ipAddress": "192.168.1.1"
}
The prefill response returns only the last 4 digits of SSN. You must collect the full SSN from the user before submitting to /v1/kyc/start.
Field Mapping
| Prefill Response | Verification Request | Notes |
|---|
firstName | firstName | Direct mapping |
middleName | middleName | Direct mapping |
lastName | lastName | Direct mapping |
email | email | Direct mapping, allow user to edit |
phoneNumber | phoneNumber | Direct mapping |
dateOfBirth | dateOfBirth | Direct mapping |
ssn (last 4) | ssn (full) | Collect full SSN from user |
address | address | Direct mapping |
| - | agreementTime | Capture when user accepts terms |
| - | referralCode | Optional, if applicable |
Complete Integration Flow
Error Handling
Common Errors
| Error | Description | Resolution |
|---|
| Invalid phone number | Phone number format is incorrect | Use E.164 format (+1XXXXXXXXXX) |
| OTP expired | OTP has expired (usually 10 minutes) | Restart the prefill flow |
| OTP invalid | Incorrect OTP entered | User should re-enter or request new OTP |
| Prefill not available | No data found for this phone/DOB | Proceed with manual verification |
Retry Logic
If OTP verification fails:
- Allow user to retry entering OTP (up to 3 attempts)
- After 3 failed attempts, require new OTP request
- Rate limit OTP requests to prevent abuse
Sandbox Testing
For testing in the sandbox environment, use these Socure test values:
Prefill Match Test Data
| Field | Value | Description |
|---|
dateOfBirth | 1985-03-30 | Sandbox DOB that returns prefill data |
phoneNumber | 14155551212 | Sandbox phone that matches prefill |
No Prefill Match Test Data
| Field | Value | Description |
|---|
dateOfBirth | 1985-03-30 | Same DOB |
phoneNumber | 12067890036 | Phone that has no prefill data |
OTP Codes
| Code | Result |
|---|
123456 | Success - returns prefilled data |
00000 (5 zeros) | Reject - OTP verification fails |
000000 (6 zeros) | Pending - verification remains pending |
Best Practices
- Validate phone format before sending to API (E.164 format)
- Display countdown timer for OTP expiration (typically 10 minutes)
- Allow users to skip prefill and enter data manually
- Pre-populate form fields with prefill data but allow editing
- Handle null fields gracefully - not all data may be available
- Collect full SSN from user since prefill only returns last 4 digits
- Track agreementTime when user accepts terms, before calling
/v1/kyc/start
