SDK Integration

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

tip

Complete the Setup guide before following this SDK Integration guide.

This is a Web Client SDK

The current SDK is for web clients. Mobile client SDKs are coming soon. If you need mobile client SDKs, please let us know so we can prioritize them.

Full Example

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

// Create session key: Call server to call POST /sessionKey with Verified API key
const SESSION_KEY = createSessionKey(); // sessionKey from POST /sessionKey

// Create SDK Instance
const verifiedClientSdk = new VerifiedClientSdk({
    environment: 'sandbox', // 'sandbox' or 'production'
    sessionKey: SESSION_KEY,
    onResult: handleResult,
    onError: handleError
});

// Handle results
function handleResult(data: SdkResult): void {
    switch (data.type) {
        case SdkResultValues.USER_SHARED_CREDENTIALS: // Success!
            // Retrieve data: Call server with data.identityUuid to call GET /1-click/{identityUuid}
        case SdkResultValues.USER_OPTED_OUT: // User clicked 'Sign Up Manually Instead'
            // Take user to manual signup flow
    }
}

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

// Show SDK to user (in document.body if no HTML element is passed)
verifiedClientSdk.show(document.getElementById('verifiedClientSdk-container')); 

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 /sessionKey.

tip

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

The response body will contain a sessionKey:

POST /sessionKey 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 /sessionKey in step 1:

const verifiedClientSdk = new VerifiedClientSdk({
    environment: 'sandbox', // 'sandbox' or 'production'
    sessionKey: 'SESSION_KEY', // sessionKey from POST /sessionKey
    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) {
    // 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. 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: // Success!
            // Retrieve data: Call server with data.identityUuid to call GET /1-click/{identityUuid}
        case SdkResultValues.USER_OPTED_OUT: // User clicked 'Sign Up Manually Instead'
            // Take user to manual signup flow
    }
}

There are 2 result values to handle:

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

To retrieve data, call your server with data.identityUuid. The server should use your Verified API key to call 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) {
    // Restart SDK: Create new session key and SDK instance
}

There are 3 error reasons to handle:

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:
        // ...
}

Go Live!

Customize SDK Styling

Remember that you can customize SDK styling in the Dashboard at any time.

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

Go to the Brand Details page for your brand.
Click the Sandbox tab in the upper right, and make sure your brand settings are synced. If they're not, click the Sync to Production button.
Click the Production tab in the upper right, and copy a Production API key from the top of the page.

note

As long as you have a contract signed with us, we will have approved you for Production access, and you'll be able to see your Production API key. If you don't see one, reach out to your Verified representative.

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. Show the SDK.​

3. Handle responses.​

a. Handle results.​

b. Handle errors.​

Go Live!​