​
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.

1

Add simple UI to your site

Add a verification button to your webpage that pings your API to generate a verification session, and then redirects to Contiguity Identity.

2

Add a webhook to your account

Listen to events as they occur in the verification flow, such as when a user submits their identity documents, or when the verification is complete.

3

Handle verification results

Use the information Contiguity provides to you to do whatever you need to do.

​
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.

1

Install the SDK

Use npm to install @contiguity/javascript

npm i @contiguity/javascript
2

Initialize the Client

After installation, import Contiguity into your project and give it your token.

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

You can also initialize it with the optional ‘debug’ flag, which logs additional information to the console.

const 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

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

The session URL is single-use and expires after 24 hours. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the end user.

​
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")

​
Cancelling a Verification Session

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

await 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.

OverviewVerification Reports