Skip to main content
POST
/
v1
/
web-sessions
/
client
Create ID Verification Web Session
curl --request POST \
  --url https://api.minervaai.io/v1/web-sessions/client \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "trackingId": "test-customer-001",
  "performScreening": true,
  "screeningFeeds": [
    "all"
  ],
  "redirectUrl": "https://minervaai.io/sessionid/custom",
  "useHosted": false,
  "nameMatchThreshold": 0.8,
  "dateMatchThreshold": 365,
  "locationMatchThreshold": 0.7,
  "locationMatchLevel": "country",
  "sessionLifetimeSeconds": 1800
}
'
{
  "status": 200,
  "message": "Token generated successfully",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJJRF8iOiJmMTA4NzkxOS05OTQwLTQ1ZTctOTlmNi02YzIwYjBlZTJiNDUiLCJJc3N1ZWRfIjoiMjAyMy0wNC0yOVQyMzo0OTo1MC4yNzQyODMyNzRaIiwiRXhwaXJ5XyI6IjIwMjMtMDQtMzBUMDA6NDk6NTAuMjc0Mjc4NTQ5WiIsIlZhbGlkXyI6dHJ1ZSwiVXNlSG9zdGVkXyI6ZmFsc2UsIlNlc3Npb25JRF8iOiI2YTg0OGVmMC04ZGQwLTQ3ODAtYWY1Zi0yMTRmN2JjNDM4MWIiLCJleHAiOjE2ODI4MTU3OTB9._gnG-3pgMXKPQU9fZqvj9DjcP8L3PCYl4xAlhAmSYJo",
  "expires": "2023-04-30T00:49:50.274278549Z",
  "sessionId": "6a848ef0-8dd0-4780-af5f-214f7bc4381b"
}

Authorizations

​
x-api-key
string
header
required

The uuidv4 API key associated with the MinervaAI account making the request.

Body

application/json
​
useHosted
boolean
required

Determines whether or not to use the hosted or embedded flow for the IDV SDK. If true, the hosted flow will be used instead of the embedded flow, which returns a link to the hosted IDV Onboarding Portal instead of popping up an iframe.

Example:

false

​
trackingId
string

The unique tracking ID that should be assigned to this session. Used by the API caller to allow the result to be more simply cross-referenced to a customer record in their database once the results are queried.

Example:

"test-customer-001"

​
performScreening
boolean

Determines whether or not to perform the AML screening after liveness and ID verification. Turning this off will remove the screening specific data collection and turn off the screening process on final submission from the IDV Onboarding Portal.

Example:

true

​
screeningFeeds
string[]

Determines which feeds should be engaged as in the AML screening component of the session. This field is required if performScreening is true, and the contents of the array must be a combination of the following, or "all":

  • "Sanctions"
  • "PEP"
  • "News"
  • "Legal"
  • "Offshore"
  • "Open Source"
  • "Ownership"
  • "Registries"
  • "Social Media"
Example:
["all"]
​
redirectUrl
string

The URL to redirect the user to if useHosted is true, and the user completes the session.

Example:

"https://minervaai.io/sessionid/custom"

​
nameMatchThreshold
number

Used in the comparison between the screening self-reported name and the IDV OCR results. If the soft match is below this percentage (represented as a decimal), then a mismatch flag will appear.

Required range: 0 <= x <= 1
Example:

0.8

​
dateMatchThreshold
number

Used in the comparison between the screening self-reported date of birth and the IDV OCR results. If the date difference is larger than this many days, then a mismatch flag will appear.

Required range: x >= 0
Example:

365

​
locationMatchThreshold
number

Used in the comparison between the screening self-reported geography and the IDV OCR results. If the soft match is below this percentage (represented as a decimal), then a mismatch flag will appear.

Required range: 0 <= x <= 1
Example:

0.7

​
locationMatchLevel
enum<string>

The lowest jurisdiction level at which the geography of the IDV OCR and screening self-reported results must match the request, where mismatches will automatically discount the records. Must be one of:

  • "address"
  • "city"
  • "state"
  • "country"
Available options:
address,
city,
state,
country
Example:

"country"

​
sessionLifetimeSeconds
number

The number of seconds that the session should be valid for. If the session is not completed within this time, the session will expire and the token will no longer be valid. If omitted, the default lifetime will be used depending on whether a sandbox or production token is being generated.

Required range: 900 <= x <= 259200
Example:

1800

Response

A new web session is generated, and the client token is returned to the API user to present to their frontend application to authenticate an end user session.

​
status
number
required
Example:

200

​
message
string
required
Example:

"Token generated successfully"

​
token
string
required

A JWT that is used by the end user to authenticate their client-side session. This token can be inserted in a URL to send to the user using the following syntax - https://idv.minervaai.io/:token/

Example:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJJRF8iOiJmMTA4NzkxOS05OTQwLTQ1ZTctOTlmNi02YzIwYjBlZTJiNDUiLCJJc3N1ZWRfIjoiMjAyMy0wNC0yOVQyMzo0OTo1MC4yNzQyODMyNzRaIiwiRXhwaXJ5XyI6IjIwMjMtMDQtMzBUMDA6NDk6NTAuMjc0Mjc4NTQ5WiIsIlZhbGlkXyI6dHJ1ZSwiVXNlSG9zdGVkXyI6ZmFsc2UsIlNlc3Npb25JRF8iOiI2YTg0OGVmMC04ZGQwLTQ3ODAtYWY1Zi0yMTRmN2JjNDM4MWIiLCJleHAiOjE2ODI4MTU3OTB9._gnG-3pgMXKPQU9fZqvj9DjcP8L3PCYl4xAlhAmSYJo"

​
sessionId
string<uuid>
required

The session ID that should be stored on your server side to be able to query the completed session data at a later point.

Example:

"6a848ef0-8dd0-4780-af5f-214f7bc4381b"

​
expires
string<date-time>
Example:

"2023-04-30T00:49:50.274278549Z"