Skip to main content

API V2 Overview

Building on the success of our V1 APIs, the V2 set brings improvements for user administration functions, policy-based verification, and a more logical trust-building sequence for users.

At its core, the V2 API uses the user account as the primary basis for building trust. This process can be accomplished via the workflows that are described below. The result is that fewer API calls are needed to forge a chain of trust, resulting in easier integration with any platform that can initiate OpenAPI requests.

Postman Sample

For your convenience we have provided sample Postman collections demonstrating the API sequence. Within the collection, the numbered requests correspond directly to the numbered sections below. Download the collection here.

API Sequence for Enrollment

1 - Authenticate

In your backend, authenticate your access and store the AccessToken and RefreshToken from the response. Before every subsequent API call, implement logic to check if the token is expired and renew it if needed.

2 - Create Account

In your backend, create a Verified account using the CreateAccount API endpoint. Below is an example of the basic account object:

Example request body:

{
"AccountNumber": "AccountV2",
"Version": 0,
"DisplayName": "Account V2",
"CustomDisplayName": "Account V2",
"Description": "Account object for V2 API",
"Rules": 1,
"Enabled": true,
"Custom": true,
"DisableReason": "",
"Email": "test@user.com",
"PhoneNumber": "1234567890",
"EmailVerified": false,
"PhoneNumberVerified": false
}

Note that the email and phone number are not required. If a user successfully completes a transaction sent via email/SMS, the phone number/email will be registered to their account and will be marked as verified.

caution

AccountNumber can be any value you specify, so you can use optionally the same GUID/username within your system. This negates the need to build a dictionary between your system and ours. However, you should avoid using spaces and special symbols in AccountNumber since this value is used in the URL path in subsequent calls.

3 - Enroll Biometrics

In your backend, call the /v2/operations endpoint with the following request body:

Example request body:

{
"AccountNumber": "AccountV2",
"Codeword": "",
"Name": "EnrollBioCredential",
"Timeout": 3600,
"TransportType": 0,
"Tag": ""
}

The AccountNumber must match the value you specified in step 1. EnrollBioCredential can only be used if the account does not already have a biometric credential associated with it. The TransportType must match one of the following values:

TransportTypeDescription
0Inline
1SMS
2Email

If a user does not have a phone number or email associated with their account, you will receive an error. Using a transport type of 0 will generate a one time secret and operation ID. Save these values from the response and use them for the next step:

Example response body:

{
"OneTimeSecret": "TbAeETwpOxbvKy7rWCeOcQ==",
"OperationId": "113e838b-be34-53e9-c52f-3cc45b2d10ce"
}

4 - Display UI for Data Capture

Use the OperationId and OneTimeSecret to build a transaction URL for one of our convenient, prebuilt UI options. You can retrieve data from this transaction using our v1 endpoints.

5 - Proof a User

In your backend, call the /v2/operations endpoint with the following request body:

Example request body:

{
"AccountNumber": "AccountV2",
"Payload": {
"DocumentTypes": [
"5"
]
},
"Codeword": "",
"Name": "GetForeignIDDocument",
"Timeout": 3600,
"TransportType": 0,
"Tag": ""
}

The AccountNumber must match the value you specified in step 1. GetForeignIDDocument can be used more than once, but it will overwrite previously uploaded documents. Once again, depending on your transport type, you will receive an operation ID and one time secret. Use these values to display the capture experience to the user. You can retrieve data from this transaction and use it to create a biometric credential using our v1 endpoints.

(Optional) - Get Document Results

During a proof transaction, you can find the status of this operation using the /v2/status endpoint. The response will return the status code.

If a user has completed the operation you can use the /v2/result endpoint along with the operation ID to retrieve the details that were captured from a document. This now includes the type of document that was captured along with the probability of a match to that document type. An example of this is shown below:

{
"Name": "GetForeignIDDocument",
"OperationId": "e09febaa-3b64-b632-1236-4f491d48b47c",
"Payload": {
"Data": {
"VerificationSteps": {
...
},
"Document": {
"Description": "Document Image",
"Type": "2",
"CapMethod": 2,
"RawData": [
...
],
"Data": [
{
"Key": "Page1Name",
"Value": "United States - Georgia Driving License (2019) Real"
},
{
"Key": "Page1Probability",
"Value": "0.96807367"
},
{
"Key": "Page2Name",
"Value": "United States - Georgia Driving License (2019) Side B"
},
{
"Key": "Page2Probability",
"Value": "0.9040118"
},
...

6 - Enroll FIDO Authenticator

In your backend, call the /v2/operations endpoint with the following request body:

Example request body:

{
"AccountNumber": "AccountV2",
"Codeword": "",
"Name": "EnrollFido2Credential",
"Timeout": 3600,
"TransportType": 0,
"Tag": ""
}

The AccountNumber must match the value you specified in step 1. EnrollFido2Credential can be used more than once per account, but note that you will receive an error if a user attempts to enroll the same device twice. Once again, depending on your transport type, you will receive an operation ID and one time secret. Use these values to display the capture experience to the user. You can retrieve data from this transaction using our v1 endpoints.

API Sequence for Verification

The new /v2/transactions endpoint allows you specify configurations for highly granular control of your authentication scenarios. The new feature with V2 is the ability to specify the CredentialType you wish to receive from a user:

CredentialTypeDescription
0Basic
1Biometrics
2OTP
4FIDO

The transport types are the same as V1:

TransportTypeDescription
0Inline
1SMS
2Email

Using a combination of these values, you gain the ability to create policies for different scenarios. For example, if you want a person to confirm their identity using a FIDO authenticator, but this confirmation should be sent to the email associated with their account, the object would appear as follows:

"ConfirmationPolicy": {
"TransportType": 2,
"CredentialType": 4
}
tip

In all scenarios, there is a Name parameter. This parameter is used to specify the template for a transaction. The template itself contains the resources needed for customizing the various transaction elements, such as email branding, text content, logos, and more.

7.1 - Verify with Basic Approval

In your backend, call the /v2/transactions endpoint with the following request body:

{
"AccountNumber": "AccountV2",
"Timeout": 3600,
"ConfirmationPolicy": {
"TransportType": 0,
"CredentialType": 0
},
"Name": "Verify_Identity"
}

This will ask a user to simply confirm or deny the transaction:

7.2 - Verify with Biometrics

In your backend, call the /v2/transactions endpoint with the following request body:

{
"AccountNumber": "AccountV2",
"Timeout": 3600,
"ConfirmationPolicy": {
"TransportType": 0,
"CredentialType": 1
},
"Name": "Verify_Identity"
}

This will prompt a user to capture a quick selfie after confirmation for comparison with their biometrics enrolled in step 3:

7.3 - Verify with OTP

In your backend, call the /v2/transactions endpoint with the following request body:

{
"AccountNumber": "AccountV2",
"Timeout": 3600,
"ConfirmationPolicy": {
"TransportType": 0,
"CredentialType": 2
},
"Name": "OTP"
}

This will send a one-time passcode to the phone number associated with a user's account which they will then enter:

7.4 - Verify with FIDO

In your backend, call the /v2/transactions endpoint with the following request body:

{
"AccountNumber": "AccountV2",
"Timeout": 3600,
"ConfirmationPolicy": {
"TransportType": 0,
"CredentialType": 4
},
"Name": "Verify_Identity"
}

This will send a request to authenticate using an enrolled FIDO authenticator. Note that depending on the transport type, a user might be asked to enroll a new device if it is sent to one that is not already enrolled on a user's account.