SDK Integration

Time to Complete	15 minutes
Time to Test and Deploy	30-60 minutes
Skills Required	Make API calls

tip

Complete the 1-Click Health 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.

Standalone 1-Click Health in the SDK is Not Yet Supported

We don't yet support using 1-Click Health standalone in the SDK (though this is coming soon). You must use it following 1-Click Signup in the SDK.

Because we don't yet support using 1-Click Health standalone in the SDK, you need to integrate 1-Click Signup with the SDK first, and then enable 1-Click Health after it. Follow the 1-Click Signup SDK Integration guide and then return to this guide to enable 1-Click Health.

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. Update how you handle responses.

a. Update how you handle results.

Update your handleResult function to include the 2 result values specific to 1-Click Health, leveraging the SdkResultValues constant:

function handleResult(data: SdkResult): void {
    switch (data.type) {
        ...
        // Add 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;
        ...
        // Add for 1-Click Health
        case SdkResultValues.NO_INSURANCE_FOUND: // No health insurance data found
            // Take user to manual health insurance flow
            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 2 result values to handle for 1-Click Health:

Result Value	Description	How to Handle
`USER_SHARED_HEALTH_DATA`	User successfully shared health insurance data	Retrieve data
`NO_INSURANCE_FOUND`	No health insurance data found	Take user to manual health insurance flow

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_HEALTH_DATA), call your server with data.healthDataUuid. The server should use your Verified API key to call GET /1-click/health/{healthDataUuid}:

GET /1-click/health/{healthDataUuid}

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.

The response will be a 1ClickHealthEntity that contains data (user health insurance and metadata):

GET /1-click/health Response Body
{
    ...1ClickHealthEntity
}

1ClickHealthEntity Example

1ClickHealthEntity Success Example
{
    "healthDataUuid": "9e12fe5b-5bb8-410a-ac6b-6e053e4c7e8d",
    "status": "SUCCEEDED",
    "results": [
        {
            "memberId": "V000000000",
            "payer": {
                "name": "FGI",
                "verifiedId": "V091767",
                "ids": ["V091767"] // ids[0] is considered primary
            },
            "edi_271": "ISA*00* *00* *ZZ*MOCK *ZZ*VERIFIED *20251117*1832*^*00501*000000002*1*P*:~GS*HB*MOCK*VERIFIED*20251117*1832*2*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*11*UNSOLICITED*20251117*1832~HL*1**20*1~NM1*PR*2*FGI*****PI*00000~HL*2*1*21*1~NM1*1P*2*PROVIDER*****XX*1234567893~HL*3*2*22*0~NM1*IL*1*Hendricks*Richard***MI*444115555~REF*SY*123341234~REF*EJ*PatAcct56789~REF*EA*MRN1234~N3*5320 Newell Rd~N4*Palo Alto*CA*94303~DMG*D8*19890801*U~DTP*291*D8*20251117~EB*1**30**PLAN~EB*D**30~MSG*PATIENT MATCH SCORE – STRONG~SE*17*0001~GE*1*2~IEA*1*000000002~"
        },
        {
            "memberId": "123456",
            "payer": {
                "name": "Aviato Health Insurance of California",
                "verifiedId": "V431835",
                "ids": ["V431835"] // ids[0] is considered primary
            },
            "edi_271": "ISA*00* *00* *ZZ*MOCK *ZZ*VERIFIED *20251117*1832*^*00501*000000003*1*P*:~GS*HB*MOCK*VERIFIED*20251117*1832*3*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*11*UNSOLICITED*20251117*1832~HL*1**20*1~NM1*PR*2*AVIATO HEALTH INSURANCE OF CALIFORNIA*****PI*00001~HL*2*1*21*1~NM1*1P*2*PROVIDER*****XX*1234567893~HL*3*2*22*0~NM1*IL*1*Hendricks*Richard***MI*XTG300M0000~REF*SY*123341234~REF*EJ*PatAcct56789~REF*EA*MRN1234~N3*5320 Newell Rd~N4*Palo Alto*CA*94303~DMG*D8*19890801*U~DTP*291*D8*20251117~EB*1**30**PLAN~EB*D**30~MSG*PATIENT MATCH SCORE – PROBABLE~SE*17*0001~GE*1*3~IEA*1*000000003~"
        }
    ]
}

1ClickHealthEntity Failure Example
{
    "healthDataUuid": "df8f8623-7fee-4ee1-aeba-14e0572b132d",
    "status": "FAILED",
    "errors": [
        {
            "message": "No coverage found"
        }
    ]
}

b. Update how you 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.

Update your handleEvent function to include the 1 event value specific to 1-Click Health, leveraging the SdkEventValues constant:

function handleEvents(event: SdkEvent): void {
    switch (event.type) {
        ...
        // Add for 1-Click Health
        case SdkEventValues.ONE_CLICK_HEALTH_FORM_SUBMITTED: 
            // User submitted health form
            console.log(event.form);
            break;
    }
}

There's 1 event value to handle for 1-Click Health:

Event Value	Description
`ONE_CLICK_HEALTH_FORM_SUBMITTED`	User submitted health insurance form

Native Mobile App Integration

The Verified SDK is a client side SDK that makes it easy to integrate 1-Click Signup 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 signup experience across all platforms.

See here in the 1-Click Signup SDK Integration guide for details.

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 Health! ✅

1. Update how you handle responses.​

a. Update how you handle results.​

b. Update how you handle events.​

Native Mobile App Integration​

Go Live!​

1. Update how you handle responses.

a. Update how you handle results.

b. Update how you handle events.

Native Mobile App Integration

Go Live!