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",
  "brand_id": "o7e2a8f6-4b7d-9e2a-7f8a-6c4e5b8d1f2a",
  "settings": {
    "test_mode": true,
    "block": false,
    "isCloseButtonShown": true,
    "shouldShowContinueOnDesktop": false,
    "isReactNative": true
  },
  "webhook": {
    "endpoint": "https://example.com"
  },
  "fn": "John",
  "ln": "Doe",
  "addr": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zip": "10001",
  "phone": "201-555-1234",
  "dob": "20000101",
  "ssn": "123-45-6789",
  "reference": "Ref123",
  "additionalData": {
    "key_1": "value_1",
    "key_2": "value_2"
  },
  "language": "en",
  "styles": {
    "colors": {
      "custom-green": [
        "#B3ECE7",
        "#8FE3DB",
        "#6BDACF",
        "#47D1C3",
        "#23C8B7",
        "#11BFA5",
        "#0AA58D",
        "#008B75",
        "#006E5D",
        "#005145"
      ]
    },
    "primaryColor": "custom-green",
    "primaryShade": 5,
    "colorScheme": "light | dark",
    "logo_url": "https://example.com/logo.png",
    "defaultRadius": "xs | sm | md | lg | xl | string | number",
    "button": {
      "radius": "xs | sm | md | lg | xl | string | number"
    }
  },
  "resultMessages": {
    "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