Create Session

Overview

The VX API provides a comprehensive solution for creating and managing user verification sessions. The process involves four main steps:

Obtaining a Bearer Token - Authenticate your application to make requests to the VX API.
Creating a Verification Session - Generate a session that returns a link for user verification.
(Optional) Embedding the Verification Link in an iFrame - Embed the verification link on your website and listen for frontend events.
Retrieving Verification Results - Obtain the results of the verification session through either a webhook or polling.

Step 1: Obtain a Bearer Token

To interact with the VX API, you must first obtain a Bearer token. This token will authenticate your application for all subsequent requests.

Endpoint

POST https://auth.dcams.app/oauth/token

Request Body

curl -X POST https://auth.dcams.app/oauth/token \
-H "Content-Type: application/json" \
-d '{
  "client_id": "{{client_id}}",
  "client_secret": "{{client_secret}}",
  "audience": "dcams.app",
  "grant_type": "client_credentials"
}'

Request Details

client_id: Provided by your administrator, this identifies your application.
client_secret: A secret key provided by your administrator for authenticating your application.
audience: Specifies the target API, which should be "dcams.app".
grant_type: Always set to "client_credentials" for this type of request.

Responses

{
    "access_token": "eyJhb...",
    "expires_in": 3600,
    "token_type": "Bearer"
}

{
    "error": "access_denied",
    "error_description": "Unauthorized"
}

{
    "error": "access_denied",
    "error_description": "Service not enabled within domain: dcams.ap"
}

Step 2: Create a Verification Session

After obtaining the Bearer token, you can create a verification session. This session will return a link that the user can use to complete the verification process.

Endpoint

POST https://vx.dcams.app/api/session/create_session

Headers

Authorization: Bearer {{access_token}} (where {{access_token}} is the token obtained from Step 1)

Required Fields

email: The user's email address. This field is used as the primary identifier of a user, but the email address does not need to be real or working as we will never send the user an email.
age: The user's age, which must be in the format "21+" (with the plus sign to indicate "age to check and over"). NOTE: "21" is just the example, please use any value that fits your use case.

Optional Fields

When sending route_id, settings_id and/or brand_id as empty fielfds the default value for each that is associated with theclient_id will always be used.

route_id: The route ID to use for this session. If not provided, the default route associated with the client_id will be used.
settings_id: Specifies the settings for the session. If not provided, default settings associated with the client_id will be used.
brand_id: Specifies the brand for the session. If not provided, a default brand associated with the client_id will be used.
There are several more optional fields in the full example below.

Request (Simple Example)

curl -X POST https://vx.dcams.app/api/session/create_session \
-H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{
  "email": "test05@veratad.com",
  "age": "21+"
}'

Request Body (Complete Example with All Optional Fields)

{
  "email": "test05@veratad.com",
  "age": "21+",
  "route_id": "p8a7b9c2-4d5e-4b7d-8e2a-4f6c9d8b1e2a",
  "settings_id": "s9d8f6c7-4b7d-8e2a-f8a7-4c5e9d8b1e2a",
  "brand_id": "o7e2a8f6-4b7d-9e2a-7f8a-6c4e5b8d1f2a",
  "webhook": {
    "endpoint": "https://example.com"
  },
  "fn": "John",
  "ln": "Doe",
  "addr": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zip": "10001",
  "phone": "201-555-1234", // any valid phone format can be used
  "dob": "20000101", // YYYYMMDD format required
  "ssn": "123-45-6789",// this can be 9 or 4 digits 
  "reference": "Ref123", // use this to populate a single reference for the session
  "additionalData": { // use this to add any key value pairs to be returned during the webhook or polling request
      "key_1": "value_1",
      "key_2": "value_2"
  },
  "language": "en",
  "resultMessages": { // dynamically set the result messages per session. 
    "success": {
      "verificationSuccessTitle": "Verification Success",
      "verificationSuccessSubTitle": "You have been verified"
    },
    "failure": {
      "verificationFailureTitle": "Verification Failure",
      "verificationFailureSubTitle": "You have not been verified"
    },
    "error": {
      "verificationErrorTitle": "System Error",
      "verificationErrorSubTitle": "Please contact customer service",
      "verificationErrorTokenTitle": "Token Error",
      "verificationErrorTokenSubTitle": "The token provided is not valid. Please check and try again.",
      "verificationErrorAlreadyVerifiedTitle": "Already Verified",
      "verificationErrorAlreadyVerifiedSubTitle": "You have already been verified. Please contact customer support.",
      "verificationErrorPendingTitle": "Pending Verification",
      "verificationErrorPendingSubTitle": "Your verification is currently pending. Please wait for further instructions.",
      "verificationErrorVelocityTitle": "Too Many Attempts",
      "verificationErrorVelocitySubTitle": "You have exceeded the number of verification attempts. Please try again later."
    }
  }
}

Responses

{
    "message": "Success",
    "detail": "Session created successfully",
    "expires_in": 3600,
    "request_id": "54bba0ca-c5c7-442d-8c6d-3cf286ccaf23",
    "link": "https://vx-fe.dcams.app/54bba0ca-c5c7-442d-8c6d-3cf286ccaf23"
}

{
    "message": "Bad JSON format",
    "detail": "Please check your JSON and try again",
}

{
  "message": "Unauthorized",
  "detail": "Missing a required input"
}


{
    "message": "Forbidden",
    "detail": "Invalid API Key or missing token",
}

{
  "message": "Already Verified", // this error only occurs if block setting is active
  "detail": "This user has a status of pass"
}

{
  "message": "Pending Review", // this only occurs if the VX app is a human review
  "detail": "The user has a manual review of an ID document in process"
}


{
    "message": "Too many requests",
    detail: "You have exceeded the amount of requests",
}

{
  "message": "Too many attempts", //this is enforced by email and visitor_id by default. In the case of creatng a session link at this time we will not have the visitor_id, and so, it will be based on email only. 
  "detail": "This user has exceeded the amount of verification sessions"
}

{
  "message": "Internal Server Error",
  "detail": "{{The reason for error if known}}"
}

PRO TIP: Use the request_id to link the session back to your database through either a webhook or a poll request. Additionally, always use the returned link value, as the domain may change at any time.

You are limited to 1,000 requests per minute to the create session endpoint. If you require a larger throughput please contact our support team.

Step 3 (Optional): Embedding the Verification Link in an iFrame

You can optionally embed the verification link returned in the response within an iFrame on your website. The iFrame will post messages to the parent window based on specific events that occur during the verification process.

iFrame Example

<iframe
  src="https://fe.dcams.app/d2568a05-47a2-4ec7-b3e3-c5bd194461a7"
  width="420"
  height="670"
  style="overflow: hidden; border: none;"
></iframe>

Listening for Post Messages

To listen for events sent from the iFrame to the parent window, you can add an event listener for the message event.

Post Message Data Structure

The post message from the iFrame to the parent window will have the following structure:

{
  "messageType": "payload",
  "value": {
    "event": "COMPLETE",
    "app": "PHONEMATCH",
    "error": "NONE"
  }
}

Sample Implementation

// Add an event listener to handle incoming messages
window.addEventListener("message", (event) => {
  // Ensure the message is from a trusted origin
  if (event.origin !== "https://vx-fe.dcams.app") return;

  // Check if the messageType is 'payload'
  if (event.data.messageType === "payload") {
    const payload = event.data.value;

    // Handle the payload as needed
    console.log("Received event:", payload.event);
    console.log("App involved:", payload.app);
    console.log("Error status:", payload.error);

    // Example: Take action based on the event type
    if (payload.event === "COMPLETE") {
      // Do something when the process is complete
    } else if (payload.event === "NEXT") {
      // Record the navigation to the next step
    }
  }
});

Response Values

Key

Possible Values

Definition

event

"NEXT"

Indicates that the application is navigating to the next step.

"CLOSED"

Indicates that the user has clicked to close the current journey.

"ERROR"

Indicates an error occurred during the journey.

"COMPLETE"

Indicates that the journey has completed.

"COMPLETE AND IN REVIEW"

Indicates that the user's journey is complete, but the last step, an ID document auto scan, failed. The agent review app is now active, and the ID is in the review queue.

app

"PHONEMATCH"

Represents the app responsible for matching phone numbers.

"DCAMS_AUTO_SCAN"

Represents the app for automated document scanning within the DCAMS suite.

"IDMATCH_KBA"

Represents the app responsible for Knowledge-Based Authentication (KBA) within the IDMATCH suite.

"DCAMS_AUTO_WITH_SELFIE"

Represents the app for document scanning with a selfie verification within the DCAMS suite.

"DCAMS_AUTO_WITH_EXPRESS"

Represents the express version of the document scanning app within the DCAMS suite.

"AGEMATCH_ESTIMATE"

Represents the app for age estimation within the AGEMATCH suite.

"IDMATCH_COPPA"

Represents the app for verifying compliance with COPPA (Children's Online Privacy Protection Act) within the IDMATCH suite.

"AGEMATCH"

Represents the main app within the AGEMATCH suite responsible for age matching.

"IDMAX_CLEAR"

Represents the CLEAR verification app within the IDMAX suite.

"IDMAX_MDL_LA"

Represents the app for LA Wallet (Mobile Driver's License) verification within the IDMAX suite.

"IDMAX_ONEID"

Represents the ONEID verification app within the IDMAX suite.

"IDMAX_DIGILOCKER"

Represents the DIGILOCKER verification app within the IDMAX suite.

"IDMAX_PLAID"

Represents the app for financial account verification using Plaid within the IDMAX suite.

"IDMAX_YOTI"

Represents the YOTI verification app within the IDMAX suite.

undefined

Represents a scenario where the current route step does not define an app, possibly due to an incomplete route sequence or an error.

error

"NONE"

Indicates that no error occurred during the process. This is the default value.

"ALREADY_DONE"

Indicates that the process has already been completed, and an attempt was made to repeat it, resulting in an error.

"PENDING"

Indictes the user's last session is still in progress becasue of a manual review

"VELOCITY"

Indicates the user has violated the amount of attempts within a 24 hour period for your settings profile

"ALREADY_VERIFIED"

Indicates the user has already been verified and your block setting is true in your settings profile

Step 4: Retrieving Verification Results

After a verification session is completed, you can retrieve the results in one of two ways:

Webhook: The results will be automatically sent to the endpoint configured with the client_id.
Polling: You can make a polling request using either the request_id from the session creation or the user's email address.

Request Body Example (Webhook or Polling)

The request body structure for both the webhook and polling methods is the same:

{
  "fn": "John",
  "ln": "Doe",
  "addr": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zip": "10001",
  "dob": "20000101",
  "email": "test05@veratad.com",
  "phone": "555-1234",
  "reference": "Ref123",
  "status": "PASS",
  "request_id": "4ed2ec66-9471-415d-99ce-7bd1742fc2b8",
  "additionalData": {
    "verificationId": "170a03b7-001c-4f81-a7a8-af580468ddb8"
  },
  "dcams_plus": {
    "document_data": {
      "FirstName": "John",
      "LastName": "Doe",
      "MiddleName": "",
      "Address": "123 Main St",
      "City": "New York",
      "State": "NY",
      "Zip": "10001",
      "CountryCode": "US",
      "FullAddress": "123 Main St, New York, NY 10001",
      "DateOfBirth": "20000101",
      "Height": "6'0\"",
      "Sex": "M",
      "EyeColor": "Brown",
      "DocumentNumber": "<REDACTED>",
      "DocumentType": "DRIVERS LICENSE",
      "SourceDocumentType": "Driver Licence",
      "NationalID": "<REDACTED>",
      "IssueDate": "20200101",
      "ExpirationDate": "20300101"
    },
    "output": {
      "vpin": {}
    },
    "api_processing_error": false,
    "service": "DCAMSPLUS5.0.Enhanced.OCR",
    "confirmation": 180199072,
    "action": "PASS",
    "detail": "ALL CHECKS PASSED",
    "issues": []
  },
  "storage": {
    "success": true
  },
  "journey": {
    "stops": [
      {
        "timestamp": "2024-08-12 13:06:50.335771",
        "type": "NEW REGISTRATION",
        "source": "",
        "status": null,
        "action": "",
        "detail": ""
      },
      {
        "timestamp": "2024-08-12 13:08:15.694983",
        "type": "SDK_Scan",
        "source": "DCAMSPLUS5.0.Enhanced.OCR",
        "status": "PASS",
        "action": "PASS",
        "detail": "ALL CHECKS PASSED"
      }
    ],
    "duration": "00h 01m 25s"
  },
  "documents": null
}

Explanation of the Response

status: Indicates whether the verification passed, failed, or is pending.
request_id: The ID of the verification session.
email: The user's email associated with the verification session.
additionalData: Contains the verificationId used internally.
dcams_plus: Contains detailed document verification data. This section is only available when using a DCAMS document verification service or an IDMax reusable ID service. The data within this object is anonymized and redacted as necessary.
journey: Provides a log of all the steps and their statuses during the verification process.
storage: Indicates whether the data was successfully stored.

This section should help you retrieve and interpret the results of a verification session, whether through a webhook or by polling the server with a request ID or email address.

PreviousTesting NextAPI Methods

Last updated 1 month ago