Skip to main content

​
KYC Verification Flow

The verification flow is the core KYC process that validates a user’s identity. This can be started after prefill or directly with user-provided information.

​
Starting Verification

​
Request

POST /v1/kyc/start

{
  "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",
  "referralCode": "REF123",
  "ipAddress": "192.168.1.1"
}

​
Request Fields

FieldTypeRequiredDescription
userIdstringYesYour internal user identifier
firstNamestringYesLegal first name
middleNamestringNoMiddle name
lastNamestringYesLegal last name
emailstringYesEmail address
phoneNumberstringYesPhone number with country code
dateOfBirthstringYesDate of birth (YYYY-MM-DD)
ssnstringYesSocial Security Number
addressobjectYesResidential address
sessionTokenstringYesSession token
agreementTimedatetimeYesWhen user agreed to terms
referralCodestringNoReferral code if applicable
ipAddressstringNoUser’s IP address

​
Address Object

FieldTypeRequiredDescription
addressLine1stringYesStreet address
addressLine2stringNoApt/Suite/Unit number
citystringYesCity
statestringYesState (2-letter code)
postalCodestringYesZIP/Postal code
countrystringYesCountry code (e.g., “US”)

​
Response

{
  "status": {
    "decision": "pending",
    "status": "in_review",
    "subStatus": "document_required",
    "externalId": "ext_abc123"
  },
  "docv": {
    "sdkKey": "a0a1869f-cf3e-4acb-919a-62b9fef30e3f",
    "docvTransactionToken": "token_xyz",
    "eventId": "event_123",
    "qrCode": "data:image/png;base64,...",
    "url": "https://verify.example.com/session/abc123"
  },
  "participantId": "",
  "account": ""
}

​
Verification Outcomes

​
Instant Approval

If the identity can be verified immediately: 
{
  "status": {
    "decision": "approved",
    "status": "complete",
    "subStatus": "",
    "externalId": "ext_abc123"
  },
  "participantId": "firms/ISV-Participant-Acme/users/user_123",
  "account": "firms/ISV-Acme/accounts/a1b2c3d4e5f6"
}
The participantId and account fields are populated only after approval. Use these identifiers for subsequent trading API calls.

​
Document Verification Required

If additional documents are needed, the response includes DocV details:
FieldDescription
sdkKeySocure SDK public key for initializing the DocV SDK
docvTransactionTokenSession token passed to the SDK’s launch() method
eventIdEvent tracking identifier
qrCodeBase64-encoded QR code image for mobile scanning
urlDirect URL for web-based document upload

​
Socure SDK Integration

For native mobile document capture, integrate the Socure DocV SDK:
  1. Initialize the SDK with sdkKey
  2. Launch verification with docvTransactionToken
  3. Poll /v1/kyc/status or use webhooks to get the final decision
Socure SDK Documentation:

​
Alternative: Web-Based Verification

If not using the SDK, users can complete document verification via:
  1. QR Code - User scans QR code with mobile device to capture documents
  2. Direct URL - User opens URL on any device to upload documents

​
Checking Status

Poll the status endpoint to track verification progress: 
GET /v1/kyc/status?externalId=ext_abc123
Response when pending: 
{
  "status": {
    "decision": "pending",
    "status": "document_review",
    "subStatus": "awaiting_review",
    "externalId": "ext_abc123"
  },
  "participantId": "",
  "account": ""
}
Response when approved: 
{
  "status": {
    "decision": "approved",
    "status": "complete",
    "subStatus": "",
    "externalId": "ext_abc123"
  },
  "participantId": "firms/ISV-Participant-Acme/users/user_123",
  "account": "firms/ISV-Acme/accounts/a1b2c3d4e5f6"
}

​
Status Values

​
Decision

ValueDescription
pendingVerification in progress
approvedIdentity verified successfully
deniedVerification failed

​
Status

ValueDescription
initiatedVerification started
in_reviewBeing reviewed
document_requiredDocuments needed
document_reviewDocuments being reviewed
completeProcess complete

​
Integration Flow

​
Best Practices

  1. Validate input before submission - Check all required fields
  2. Use webhooks if available - Don’t rely solely on polling
  3. Handle all decision states - Show appropriate UI for each
  4. Store externalId - You’ll need it to check status later
  5. Implement retry logic - API calls may occasionally fail
  6. Log all responses - For debugging and compliance