Create Session

Overview

The VX API provides a comprehensive solution for creating and managing verification sessions. This guide covers:

  1. Authentication - Obtain a bearer token for authorization.

  2. Create Session - Generate a verification session link.

  3. Get Session Status - Obtain the results through a webhook or polling.

  4. iFrame Integration (optional) - Embed the verification link and handle post message events.


Authentication

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"
}

Create 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 the Authentication step)

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": "[email protected]",
  "age": "21+"
}'

Request Body (Complete Example with All Optional Fields)

{
  "email": "[email protected]",
  "age": "21+",
  "route_id": "p8a7b9c2-4d5e-4b7d-8e2a-4f6c9d8b1e2a",
  "settings_id": "s9d8f6c7-4b7d-8e2a-f8a7-4c5e9d8b1e2a", // in most cases you can just use a settings_id profile or use the settings object below to set on the fly
  "brand_id": "o7e2a8f6-4b7d-9e2a-7f8a-6c4e5b8d1f2a",
  "settings": {
    "test_mode": true,
    "block": false,
    "isCloseButtonShown": true,
    "shouldShowContinueOnDesktop": false
  },
  "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"
}

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.


Last updated