Create Session
Overview
The VX API provides a comprehensive solution for creating and managing verification sessions. This guide covers:
Authentication - Obtain a bearer token for authorization.
Create Session - Generate a verification session link.
Get Session Status - Obtain the results through a webhook or polling.
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
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"
}
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.
Last updated