SDK Integration

Time to Complete	1 hour
Time to Test and Deploy	2-4 hours
Skills Required	Make API calls

tip

Complete the 1-Click Signup Setup guide before following this SDK Integration guide.

The SDK Works for Web and Native Mobile

You can use the Verified SDK in both web and native mobile apps! Many of our customers do exactly this, so they can provide users with a unified (and much easier to maintain) experience across web, iOS, and Android.

For how to do this, see Native Mobile App Integration.

Full Example

Integrate SDK
import {
    VerifiedClientSdk,
    SdkResult,
    SdkEvent,
    SdkError,
    SdkResultValues,
    SdkEventValues,
    SdkErrorReasons,
} from '@verifiedinc-public/client-sdk';

// Initialize the SDK
const sdk = new VerifiedClientSdk({
    sessionKey: 'YOUR_SESSION_KEY',
    onResult: handleResult,
    onError: handleError,
    onEvent: handleEvent,
});

// Handle successful results
function handleResult(data: SdkResult) {
    switch (data.type) {
        case SdkResultValues.USER_SHARED_CREDENTIALS: // 1-Click Signup success!
            // Pass data.identityUuid to server (to call GET /1-click/{identityUuid})
            break;
        // Only for 1-Click Health
        // case SdkResultValues.USER_SHARED_HEALTH_DATA: // 1-Click Health success!
        //     // Pass data.healthDataUuid to server (to call GET /1-click/health/{healthDataUuid})
        //     break;
        case SdkResultValues.USER_OPTED_OUT: // User clicked 'Sign Up Manually Instead'
            // Take user to manual signup flow
            break;
        case SdkResultValues.NO_CREDENTIALS_FOUND: // No signup data found (OCE013 Verified error code)
            // Take user to manual signup flow. Additional metadata may be available.
            break;
        // Only for 1-Click Health
        // case SdkResultValues.NO_INSURANCE_FOUND: // No health insurance data found
        //     // Take user to manual health insurance flow
        //     break;
        case SdkResultValues.RISK_SCORE_TOO_HIGH: // OCE017 Verified error code
            // Take user to manual signup flow. Additional metadata may be available.
            break;
        case SdkResultValues.MAX_INPUT_ATTEMPTS_EXCEEDED: // OCE019 Verified error code
            // Take user to manual signup flow. Additional metadata may be available.
            break;
        case SdkResultValues.MAX_VERIFICATION_CODE_ATTEMPTS_EXCEEDED: // User tried verification code too many times
            // Take user to manual signup flow. Additional metadata may be available.
            break;
    }
}

// Handle errors
function handleError(error: SdkError) {
    console.error('SDK error:', error.reason);
    switch (error.reason) {
        case SdkErrorReasons.INVALID_SESSION_KEY:
            // Call POST /sessionKey on server to get a new session key
            break;
        case SdkErrorReasons.SESSION_TIMEOUT:
            // Call POST /sessionKey on server and create new VerifiedClientSdk instance
            break;
        case SdkErrorReasons.SHARE_CREDENTIALS_ERROR:
            // Handle credential sharing error
            break;
    }
}

// Handle intermediary events
function handleEvent(event: SdkEvent) {
    // metadata is always available
    console.log(event.metadata);
    switch (event.type) {
        case SdkEventValues.SDK_READY:
            // SDK rendered content for the user
            break;
        case SdkEventValues.USER_STEP_CHANGE:
            // User navigated to a new step
            console.log(event.step, event.previousStep);
            break;
        case SdkEventValues.STEP_TIME_SPENT:
            // User left a step, includes duration
            console.log(event.step, event.durationMs);
            break;
        case SdkEventValues.USER_COMPLETED_PRODUCT:
            // User completed a product flow
            console.log(event.product);
            break;
        case SdkEventValues.ONE_CLICK_SIGNUP_FORM_SUBMITTED:
            // User submitted signup form
            console.log(event.form);
            break;
        case SdkEventValues.ONE_CLICK_HEALTH_FORM_SUBMITTED: // Only for 1-Click Health
            // User submitted health form
            console.log(event.form);
            break;
    }
}

// Display the SDK in your application
sdk.show(document.getElementById('sdk-container') as HTMLElement);

1. Create a session key.

Have your client call your server to create a session key. The server should use your Verified API key to call POST /client/1-click.

tip

You can access your API keys in the Dashboard: see the Setup guide.

In typical usage, you call this endpoint with an empty request body:

POST /client/1-click Request Body (empty)
{}

But you can include properties (all of which are optional) if you have them:

POST /client/1-click Request Body
{
    verificationUuid?: string,
    phone?: string,
    email?: string,
    birthDate?: string,
    ssn4?: string,
    fullName?: {
        firstName?: string,
        middleName?: string,
        lastName?: string
    },
    address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        zipCode?: string,
        country?: string
    }
}

Include verificationUuid if you're using the SDK after Text to Signup or a 1-Click Verify API integration.
Include phone if you already verified the user's phone number with your own solution (outside of Verified). This requires approval through a compliance review.
Include other properties if you already have some input user data. This will cause the SDK to optimize the flow to avoid rendundant steps (for example by skipping the Birthday step if that has already been provided).

If you include either verificationUuid or phone:

The SDK will skip the Phone and Verification Code steps, since the user has already verified their phone number.
The SDK will start with a separate Consent step, since the consent language can't be displayed on the Phone step.

note

It doesn't make sense to include both verificationUuid and phone, since a verificationUuid references a 1ClickVerificationEntity, which has its own phone property.

The response body will contain a sessionKey:

POST /client/1-click Response Body
{
    sessionKey: string
}

If you get an error with Verified error code SKE001, you need to change your brand's integration type setting. Go to the Brand Details page in the Dashboard and change that setting to SDK.

Your server should return the sessionKey to your client, so you can use it in step 2.

danger

Never use Verified API keys client side. Only use them server side. Verified API keys allow you to source sensitive data about users, so you must keep them secure. If you use a Verified API key client side, our firewall will block your request, and you'll get this firewall error.

Session Keys Are Single Use

Each session key can only be used once. If you need to initialize a new SDK instance, create a new session key.

2. Initialize the SDK.

Make sure you've installed the SDK:

Install SDK with NPM
npm i @verifiedinc-public/client-sdk

Then, initialize the SDK as follows.

a. Import the SDK.

Import the SDK into your application:

import { VerifiedClientSdk, SdkResult, SdkError, SdkResultValues, SdkErrorReasons } from '@verifiedinc-public/client-sdk';

b. Create an SDK instance.

Create a VerifiedClientSdk instance, setting the environment and passing the sessionKey you received from POST /client/1-click in step 1:

const verifiedClientSdk = new VerifiedClientSdk({
    environment: 'sandbox', // 'sandbox' or 'production'
    sessionKey: 'SESSION_KEY', // sessionKey from POST /client/1-click
    onResult: handleResult, // Result function
    onError: handleError // Error function
});

Use Sandbox for Development and Testing

Please do all development work and testing against our Sandbox environment, which returns mock data. You can use our Production environment when you're ready to go live.

c. Define a result function.

Define a function to handle results, leveraging the SdkResult type:

function handleResult(data: SdkResult): void {
    // See step 3a
}

See step 3a for how to handle results.

d. Define an error function.

Define a function to handle errors, leveraging the SdkError type:

function handleError(error: SdkError) {
    // See step 3b
}

See step 3b for how to handle errors.

e. Define an event function.

Define a function to handle events, leveraging the SdkEvent type:

function handleEvent(event: SdkEvent) {
    // See step 3c
}

See step 3c for how to handle events.

f. Show the SDK.

Show the SDK to the user, leveraging the show() method.

// Injected into document.body if no HTML element is passed)
verifiedClientSdk.show(document.getElementById('verifiedClientSdk-container')); 

note

There's also a destroy() method that destroys the SDK element and invalidates the instance.

3. Handle responses.

a. Handle results.

Complete the handleResult function you defined in step 2c, leveraging the SdkResultValues constant:

function handleResult(data: SdkResult): void {
    switch (data.type) {
        case SdkResultValues.USER_SHARED_CREDENTIALS: // 1-Click Signup success!
            // Pass data.identityUuid to server (to call GET /1-click/{identityUuid})
            break;
        // Only for 1-Click Health
        // case SdkResultValues.USER_SHARED_HEALTH_DATA: // 1-Click Health success!
        //     // Pass data.healthDataUuid to server (to call GET /1-click/health/{healthDataUuid})
        //     break;
        case SdkResultValues.USER_OPTED_OUT: // User clicked 'Sign Up Manually Instead'
            // Take user to manual signup flow
            break;
        case SdkResultValues.NO_CREDENTIALS_FOUND: // No signup data found (OCE013 Verified error code)
            // Take user to manual signup flow. Additional metadata may be available.
            break;
        // Only for 1-Click Health
        // case SdkResultValues.NO_INSURANCE_FOUND: // No health insurance data found
        //     // Take user to manual health insurance flow
        //     break;
        case SdkResultValues.RISK_SCORE_TOO_HIGH: // OCE017 Verified error code
            // Take user to manual signup flow. Additional metadata may be available.
            break;
        case SdkResultValues.MAX_INPUT_ATTEMPTS_EXCEEDED: // OCE019 Verified error code
            // Take user to manual signup flow. Additional metadata may be available.
            break;
        case SdkResultValues.MAX_VERIFICATION_CODE_ATTEMPTS_EXCEEDED: // User tried verification code too many times
            // Take user to manual signup flow. Additional metadata may be available.
            break;
    }
}

note

Regardless of the result type, you can access specific metadata properties directly from the data object. See SdkResult type definition for the complete structure.

There are 6 result values to handle for 1-Click Signup:

Result Value	Description	How to Handle
`USER_SHARED_CREDENTIALS`	User successfully shared credentials (identity data)	Retrieve data
`USER_OPTED_OUT`	User opted out by clicking the "Sign Up Manually Instead" button	Take user to manual signup flow
`NO_CREDENTIALS_FOUND`	No signup data found (`OCE013` Verified error code)	Take user to manual signup flow. Additional metadata may be available.
`RISK_SCORE_TOO_HIGH`	`OCE017` Verified error code	Take user to manual signup flow. Additional metadata may be available.
`MAX_INPUT_ATTEMPTS_EXCEEDED`	`OCE019` Verified error code	Take user to manual signup flow. Additional metadata may be available.
`MAX_VERIFICATION_CODE_ATTEMPTS_EXCEEDED`	`OCE020` Verified error code	Take user to manual signup flow. Additional metadata may be available.

note

There are 2 other result values, but these are only relevant for 1-Click Health. See the 1-Click Health SDK Integration guide for details. ::

Some metadata may be available directly in the data object (see SdkResult). To retrieve all metadata (and credentials if the result value is USER_SHARED_CREDENTIALS), call your server with data.identityUuid. The server should use your Verified API key to call GET /1-click/{identityUuid}:

GET /1-click/{identityUuid}

danger

The response will be a 1ClickEntity that contains data (user credentials and metadata):

GET /1-click Response Body
{
    ...1ClickEntity
}

1ClickEntity Example

1ClickEntity Example
{
    "identifiers": {
        "phone": "+12125550010"
    },
    "credentials": {
        "fullName": {
            "firstName": "Richard",
            "lastName": "Hendricks"
        },
        // Array because `multi` was set to `true` in the address credential request
        "address": [
            {
                "line1": "5320 Newell Rd",
                "city": "Palo Alto",
                "state": "CA",
                "zipCode": "94303",
                "country": "US"
            }
        ],
        "birthDate": "1989-08-01",
        "ssn": "000456789"
    },
    "metadata": {
        "identifiers": {
            "verificationMethod": {
                "phone": "otp"
            },
            "riskSignals": {
                "overall": {
                    "score": 0, // included in Basic
                    "level": "low", // included in Basic
                    "recommendation": "allow", // included in Basic
                    "reasonCodes": [ // included in Advanced
                        "OCR10021"
                    ]
                },
                "phone": { // included in Advanced
                    "carrier": {
                        "id": 0,
                        "name": "Example Carrier"
                    }
                    "reasonCodes": [
                        "OCR20004",
                        "OCR20005",
                        "OCR20007",
                        "OCR20101"
                    ]
                },
                "email": { // included in Advanced
                    "reasonCodes": [
                        "OCR60001",
                        "OCR60002"
                    ]
                }
            }
        },
        // Follows the same structure as `credentials` and maintains the same order for array items when `multi` is set to `true`
        "credentials": {
            "verificationMethod": {
                "fullName": {
                    "firstName": "phone_carrier",
                    "lastName": "phone_carrier"
                },
                // Array because `multi` was set to `true` in the address credential request
                "address": [
                    {
                        "line1": "credit_bureau",
                        "city": "credit_bureau",
                        "state": "credit_bureau",
                        "zipCode": "credit_bureau",
                        "country": "credit_bureau"
                    }
                ],
                "birthDate": "phone_carrier",
                "ssn": "phone_carrier"
            }
        }
    }
}

b. Handle errors.

Complete the handleError function you defined in step 2d:

function handleError(error: SdkError): void {
    // Restart SDK: Create new session key and SDK instance
}

There are 3 error reasons to handle for 1-Click Signup:

Error Reason	Description	How to Handle
`INVALID_SESSION_KEY`	Session key (used in step 2b) is invalid	Restart SDK
`SESSION_TIMEOUT`	Session timed out	Restart SDK
`SHARE_CREDENTIALS_ERROR`	There was an error when the user tried to share credentials (identity data)	Restart SDK

We recommend you handle all error reasons by restarting the SDK. To do so, create another session key (step 1) and initialize a new SDK instance (step 2).

How to Handle Error Reasons Differently

If you prefer to handle each error reason differently, you can certainly do so by leveraging the SdkErrorReasons constant:

switch (error.reason) {
    case SdkErrorReasons.INVALID_SESSION_KEY:
        // ...
    case SdkErrorReasons.SESSION_TIMEOUT:
        // ...
    case SdkErrorReasons.SHARE_CREDENTIALS_ERROR:
        // ...
}

c. Handle events.

tip

Handling events is not necessary for the SDK to work, but it will allow you to understand how users are interacting with the SDK and optimize the experience.

Complete the handleEvent function you defined in step 2e, leveraging the SdkEventValues constant:

function handleEvents(event: SdkEvent): void {
    switch (event.type) {
        case SdkEventValues.SDK_READY:
            // Web app rendered the content
            break;
        case SdkEventValues.USER_STEP_CHANGE:
            // User navigated to a new step
            console.log(event.step, event.previousStep);
            break;
        case SdkEventValues.STEP_TIME_SPENT:
            // User left a step, includes duration
            console.log(event.step, event.durationMs);
            break;
        case SdkEventValues.USER_COMPLETED_PRODUCT:
            // User completed a product flow
            console.log(event.product);
            break;
        case SdkEventValues.ONE_CLICK_SIGNUP_FORM_SUBMITTED:
            // User submitted signup form
            console.log(event.form);
            break;
        // Only for 1-Click Health
        // case SdkEventValues.ONE_CLICK_HEALTH_FORM_SUBMITTED: 
        //     // User submitted health form
        //     console.log(event.form);
        //     break;
    }
}

There are 5 event values to handle for 1-Click Signup:

Event Value	Description
`SDK_READY`	SDK rendered content for the user
`USER_STEP_CHANGE`	User navigated to a new step
`STEP_TIME_SPENT`	User left a step, includes duration
`USER_COMPLETED_PRODUCT`	User completed a product flow
`ONE_CLICK_SIGNUP_FORM_SUBMITTED`	User submitted signup form

note

There's 1 other event value, but this is only relevant for 1-Click Health. See the 1-Click Health SDK Integration guide for details.

Native Mobile App Integration

The Verified SDK is a client side SDK that can be integrated into any application. Because it’s web based, the SDK can be easily used within both web and native mobile apps.

tip

Using a single SDK across all types of apps makes it far easier to maintain. We highly recommend you do this if you have mobile apps! The result will be unified, easy to maintain experience across all platforms.

For native mobile apps, the SDK should be rendered within a WebView. By using the right type of WebView, and by opening and closing it on appropriate triggers, the SDK can be made to feel like a seamless part of the native app. Below, we provide guidance for integration strategy and include a full example of a React Native app integration.

Integration Strategy

Implementing the Verified SDK in a native mobile app has three parts:

JavaScript bridge between the WebView and application. In the example below, it is the injected code.
Message handler. In the example below, it happens through the React Native postMessage method.
UI handler. In the example below, we create a VerifiedSDK component inside the codebase that renders a React Native WebView (from the react-native-webview library).

Full Example

Setup

Usage

Session Key Generation

Go Live!

When you're ready to go live, get a Production API key:

Go to the Brand Details page for your brand in the Verified Dashboard.
Click the Production tab in the upper right, and make sure your brand settings are configured as you intend them to be.
Copy a Production API key from the top of the page.

tip

You can use the Sync from Sandbox buttons to quickly port some setting configurations from Sandbox to Production. Note, however, that this is not possible for all settings: some need to be configured manually for Production.

Just swap Sandbox for Production:

Swap your Sandbox API key for your Production API key.
Swap the Sandbox base URL for the Production base URL.
Swap 'sandbox' for 'production' in the environment attribute of the SDK instance (see step 2b).

Then you'll be live with 1-Click Signup! ✅

1. Create a session key.​

2. Initialize the SDK.​

a. Import the SDK.​

b. Create an SDK instance.​

c. Define a result function.​

d. Define an error function.​

e. Define an event function.​

f. Show the SDK.​

3. Handle responses.​

a. Handle results.​

b. Handle errors.​

c. Handle events.​

Native Mobile App Integration​

Integration Strategy​

Full Example​

Setup​

Usage​

Session Key Generation​

Go Live!​

1. Create a session key.

2. Initialize the SDK.

a. Import the SDK.

b. Create an SDK instance.

c. Define a result function.

d. Define an error function.

e. Define an event function.

f. Show the SDK.

3. Handle responses.

a. Handle results.

b. Handle errors.

c. Handle events.

Native Mobile App Integration

Integration Strategy

Full Example

Setup

Usage

Session Key Generation

Go Live!