Verification Sessions

​

Before you begin

1. Make sure your account is on a plan that supports Identity - either PAYG (Pay-As-You-Go), Unlimited, or Enterprise.
2. Register for an Identity Entitlement in the Dashboard. This onboarding process is separate from your main Contiguity account onboarding.

​

How it’s going to work

Contiguity Identity handles the heavy lifting - all you need to do is redirect your customer to a unique session URL that Contiguity provides.

​

Getting Started

​

Install the SDK

Contiguity is working on adding several SDKs over the coming months, including ones for Swift, Java, Dart, and more.

SDKs not available in the language you need? You can use the Identity API directly.

npm i @contiguity/javascript

npm i @contiguity/javascript

pip install contiguity

const contiguity = require('@contiguity/javascript')
const client = contiguity.login("your token here")

const client = contiguity.login("your token here", true)

const contiguity = require('@contiguity/javascript')
const client = contiguity.login("your token here")

const client = contiguity.login("your token here", true)

import contiguity
client = contiguity.login("your_token_here")

client = contiguity.login("your_token_here", True)

​

Create a Verification Session

You will need a server-side endpoint to create a Verification Session, as this prevents malicious users from overriding verification options and incurring charges on your account. Add authentication to this endpoint by including a client reference in the session metadata, or by storing the Verification Session ID in your database.

​

Example Request

const verificationSession = await client.identity.verificationSessions.create({
    type: "document",
    options: {
        allowed_document_types: ["passport", "id_card", "driving_license"], 
        require_live_capture: true,
        require_selfie: true,
    },
    return_url: "https://your-website.com/verify-callback"
})

return verificationSession.url // return ONLY the session URL to the frontend

const verificationSession = await client.identity.verificationSessions.create({
    type: "document",
    options: {
        allowed_document_types: ["passport", "id_card", "driving_license"], 
        require_live_capture: true,
        require_selfie: true,
    },
    return_url: "https://your-website.com/verify-callback"
})

return verificationSession.url // return ONLY the session URL to the frontend

verification_session = client.identity.verificationSessions.create(
    type="document",
    options={
        "allowed_document_types": ["passport", "id_card", "driving_license"],
        "require_live_capture": True,
        "require_selfie": True,
    },
    return_url="https://your-website.com/verify-callback"
)

return verification_session.url # return ONLY the session URL to the frontend

This will generate a Verification Session object, which contains a URL that you will need to redirect the user to begin the verification process.

​

Parameters

​

Get a Verification Session

Sometimes, you may need to get a Verification Session that you previously created. You can do this by calling the get method on verificationSessions with the Verification Session ID.

const verificationSession = await client.identity.verificationSessions.get("vs_id")

const verificationSession = await client.identity.verificationSessions.get("vs_id")

verification_session = client.identity.verificationSessions.get("vs_id")

​

Cancelling a Verification Session

You can cancel a Verification Session using the client.identity.verificationSessions.cancel method.

await client.identity.verificationSessions.cancel("vs_id");

await client.identity.verificationSessions.cancel("vs_id");

client.identity.verificationSessions.cancel("vs_id")

​

Handling Verification Session Outcomes

As listed in Webhook v2 Events, you can listen for events as they occur in the verification flow. Verification Session outcomes can be:

• identity.verification_session.verified
• identity.verification_session.failed
• identity.verification_session.requires_input
• identity.verification_session.manually_approved
• identity.verification_session.manually_denied

​

Handling Successful Verification

This event is sent when Contiguity has successfully verified the user’s identity. You can use this event to mark the user as verified in your database, or to fetch more information about the user using the Verification Report ID.

​

Handling Verification Requires Input

An identity.verification_session.requires_input event is sent one at least one of the checks Contiguity performs failed. When receiving this event, you’ll have access to error.code and error.message to help you understand why the verification requires your input. You can review the user’s information in the Dashboard to approve or deny them at any time.

​

Error Codes

Depending on your use case, you might want to allow your users to retry the verification if it fails. We recommend that you limit the amount of submission attempts. When handling this event, you might also consider notifying the user that their verification failed, opening a support ticket for them, or providing them an alternative verification method.

​

Handling Failed Verification

The identity.verification_session.failed event is sent when Contiguity has failed to verify the user’s identity, and believes that the user is not who they say they are, with accuracy greater than 99%. This includes an obviously fake ID, attempting to circumvent selfie verification (i.e. using a printed out photo), or other obvious attempts to circumvent the verification process.

You can use this event to notify the user that their verification failed, and to provide them with an alternative verification method.