# 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. **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

```bash
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

{% tabs %}
{% tab title="200 OK" %}

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

{% endtab %}

{% tab title="401 Unauthorized" %}

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

{% endtab %}

{% tab title="403 Forbidden" %}

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

{% endtab %}
{% endtabs %}

***

## 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

{% hint style="info" %}
When sending `route_id`, `settings_id` and/or `brand_id` as empty fielfds the default value for each that is associated with the`client_id` will always be used.
{% endhint %}

* **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.
* **styles**: Customize the appearance of the VX experience. See [Styles](https://api.veratad.com/vx/styles) for a full list of options.
* **webhook.endpoint**: Provide the HTTPS endpoint that should receive VX webhook callbacks for this session. Make sure the endpoint is reachable from the public internet.
* There are several more optional fields in the full example below.

{% hint style="info" %}
Webhook deliveries can be protected with either Basic Authentication credentials or an HMAC signature header. Coordinate with your Veratad representative to receive the credentials or signing secret, and validate every webhook before processing it.
{% endhint %}

### Request (Simple Example)

```bash
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)

For detailed styling options, see [Styles](https://api.veratad.com/vx/styles).

```json
{
  "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",
  "settings": {
    "test_mode": true,
    "block": false,
    "isCloseButtonShown": true,
    "shouldShowContinueOnDesktop": false,
    "isReactNative": true,
    "isFooterShown": 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",
  "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"
    },
    "components": {
      "button": {
        "color": "#000000"
      }
    },
    "assets": {
      "icons": {
        "handoff.header.main": {
          "alt": "Brand",
          "url": "https://example.com/images/logo.svg",
          "srcset": {
            "2x": "https://example.com/images/logo@2x.svg",
            "3x": "https://example.com/images/logo@3x.svg"
          },
          "width": 100,
          "height": 100
        }
      }
    },
    "global": {
      "typography": {
        "font": {
          "family": "SpaceGrotesk",
          "normal": {
            "url": "https://example.com/fonts/SpaceGrotesk-Regular.ttf",
            "format": "truetype"
          }
        }
      }
    }
  },
  "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

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "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"
}
```

{% endtab %}

{% tab title="400 Bad Request" %}

<pre class="language-json"><code class="lang-json">{
    "message": "Bad JSON format",
<strong>    "detail": "Please check your JSON and try again",
</strong>}
</code></pre>

{% endtab %}

{% tab title="401 Unauthorized" %}

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

{% endtab %}

{% tab title="403 Forbidden" %}

```json

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

```

{% endtab %}

{% tab title="423 Locked" %}

```json
{
  "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"
}
```

{% endtab %}

{% tab title="429 Too Many Requests" %}

```json

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

```

{% endtab %}

{% tab title="500 Internal Server Error" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**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.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

***