Web Quick Start

You can use identity proofing to securely verify the identity of your customers using documents like their driver’s license or passport–such as before allowing them to open a new bank account online or pick up a rental car. This describes how to quickly integrate identity proofing into your website.

Stay tuned...

A new and improved version of the Identity Proofing APIs is coming out soon.

How it works

Here's an example of a basic integration flow. Transmit APIs are shown in pink along with the relevant integration step.

When the user performs an action requiring identity proofing, a session is created from the backend to establish a secure context for the flow (Step 3). Your app redirects the user to the Transmit identity proofing experience (Step 4). Once the user completes the verification process, the browser is redirected back to your app to indicate the process completed. You can now get the verification result (Step 5), and then proceed accordingly.

Step 1: Create your app

To integrate with Transmit, you'll need to create an application in the Admin Portal (if you don’t have one yet).

  1. From Applications , click Add application .
  2. Add the friendly application name to display in the Admin Portal.
  3. Add a client display name, and your website URL as a redirect URI (e.g., https://your-domain.com ).
    Note

    These fields are required but won’t be used for the identity proofing flow.

  4. Click Add to create your application. This will automatically generate your client credentials.

Step 2: Get access token

You’ll need an OAuth2 bearer access token to authorize the backend API requests. Using the client ID and client secret of your Transmit application, send this request from your backend to generate an access token:

Copy
Copied
 curl --location --request POST 'https://api.userid-stg.io/oidc/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=client_credentials' \
 --data-urlencode 'client_id=[CLIENT_ID]' \
 --data-urlencode 'client_secret=[CLIENT_SECRET]'
Note

The token must remain secure on your server, and must only be used for backend requests.

Step 3: Start session

A session is required to provide a secure context for the identity proofing flow. Using the access token generated in Step 2, start a session by sending a backend request like this (using your preferred HTTP lib/tool):

Copy
Copied
 curl --location --request POST 'https://verifyid-sandbox.io/api/v1/merchant/start-session' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer [ACCESS_TOKEN]' \
 --data-raw '{
     "expiration_in_seconds": 3600,
     "state": "12345",
     "redirect_url": "https://httpbin.org/get"
 }'
  • redirect_url is the page the user will be redirected to when the verification process is completed. It was set to httpbin in this example for demo purposes (since it allows you to see the exact callback format), but you can replace it with any URL or even deep link to your app if applicable.
  • state should be replaced with a unique token per request. It will be returned in the redirect URL so you can use it to match the verification result with this request.

The response includes the session ID of the created session, to use in subsequent API requests. For example:

Copy
Copied
 {
    "session_id": "ca766ed78c8c0b7824dfea356ed30b72",
 }

Step 4: Initiate ID proofing

After starting the session and obtaining the session ID, initiate the verification process by redirecting the user to the following page, which will guide them through the entire identity proofing flow:

Copy
Copied
 https://verifyid-sandbox.io/verify/[SESSION_ID]

For desktop devices:

In this phase, the identity proofing UI is optimized for mobile. It still works on desktop, but the experience is sub-optimal. If the user is on a desktop, redirect them to a mobile device to perform the verification process. We suggest displaying a QR code (encoding the URL above) that the user will scan to initiate the process on mobile. In an upcoming phase, the desktop-to-mobile UI will be provided by Transmit as well.

Step 5: Get verification result

Once the verification is completed, the user is redirected back to your website to the redirect URL specified in the session start request. The URL will include the state from your request, and the session ID. For example:

Copy
Copied
 https://httpbin.org/get?state=12345&sessionId=ca766ed78c8c0b7824dfea356ed30b72

Using the access token from Step 2 and the session ID, get the verification result by sending this backend request:

Copy
Copied
 curl --location --request POST 'https://verifyid-sandbox.io/api/v1/merchant/status' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer [ACCESS_TOKEN]' \
 --data-raw '{
     "session_id": [SESSION_ID]
 }'

For desktop devices:

After displaying the QR code on the desktop device, you can start polling for the verification status by sending a request like the one above. For example, you can use this to update the desktop experience once the user completes the verification process on their mobile device.

Step 6: Handle verification result

Your app should define the user experience based on the verification result, indicated by the state field. Note that this field indicates the verification state and is not the same field as the one returned in the redirect URL.

If returned as verified, the identity proofing process was completed successfully. The response will include some user details collected from the document (like their name and birthday) which can be used to enrich the user’s profile, and details about the document used to prove their identity. See the example below.

If returned as rejected, the identity proofing process didn’t succeed since at least one verification check didn’t pass. You should proceed as suitable for your use case, typically by initiating a manual review process.

Here’s an example of a successful verification result:

Copy
Copied
 {
    "state": "verified",
    "sessionId": "[session_id]",
    "personDetails": {
        "givenName": "string",
        "surname": "string",
        "dateOfBirth": "ISO-8601 date string",
        "full_name": "string",
        "nationalId": "country code"
    },
    "documentDetails": {
        "type": "string",
        "country": "country code",
        "documentId": "string",
        "validFrom": "ISO-8601 date string",
        "validUntil": "ISO-8601 date string"
    }
 }