Skip to main content

​
Before you begin

  1. Make sure your account is on a plan that supports Identity - either Usage (Pay Per Use), Unlimited, or Enterprise.
  2. Register for an Identity Entitlement in the Console. 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

  • JavaScript
  • Python
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.
  • JavaScript
  • Python
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

  • JavaScript
  • Python
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

The type of verification session to create. Currently, only document is supported.
A unique identifier for the user. This is useful if you want to link the Verification Session to a user in your database.
Any key-value pairs you want to store with the verification session.
Options for the verification session.
An array of document types that the user can upload. Available options are passport, id_card, and driving_license.
Whether to require the user to capture their document live with their device’s camera.
Whether to require the user to take a selfie.
Whether to verify the user’s phone number.
Whether to verify the user’s email.
The URL to redirect the user to after they complete the verification.

​
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.
  • JavaScript
  • Python
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.
  • JavaScript
  • Python
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 Console to approve or deny them at any time.

​
Error Codes

  • Session
  • Document
  • Selfie
  • Fraud Detection Triggered
This user can’t be verified because they are underage. Contiguity doesn’t verify users under the age of majority in their country of residence.
This user can’t be verified because the ID from their country is not supported.
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.
⌘I