Create verification session

A verification session is used to pass end-user data to Helium ID and receive verification results from Helium ID. Current article explains how to start a verification session.

Create with POST /verifications call

Before you start:

• Refer to API prerequisites and make sure you have all you need to start sending API requests.
• Ensure you have your API Key. You can generate this in your Helium ID Dashboard.

For API

Make a POST /v1/verifications call:

1. Send the verification object to https://server.heliumid.io/api/v1/verifications (*required)
2. Include the Content-Type: application/json header (*required)
3. Include the x-api-key header containing your integration’s API key (*required)
4. Include the vendorData parameter (strongly recommended for identifying the session on your end)
5. Optionally include the meta parameter to pass additional custom data
6. Optionally specify the method as auto (default, uses automated systems) or manual (reviewed by an Identity Specialist)
7. Check the response .json and record the unique session link in data.link, required to bring the end-users to the verification flow.

Sample request

The example below uses placeholder data.

cURL

curl -X POST \
  --url 'https://server.heliumid.io/api/v1/verifications' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "vendorData": "user_12345",
    "method": "auto",
    "meta": {
      "key": "value"
    }
}'

Sample response

The example below uses placeholder data.

JSON

{
  "status": true,
  "message": "Created verification",
  "data": {
    "link": "https://verify.heliumid.io/?processId=69d4f7657bcbe3b58b96b2f7",
    "verificationId": "69d4f7657bcbe3b58b96b2f7"
  },
  "code": 200
}

---

Create Manually

It is possible to manually generate a verification session in the Helium ID Dashboard. This option can be used to test or debug sessions, or as a manual fallback option.

The manual option creates a link that you can share with the end-user.

1. Go to your Helium ID Dashboard
2. Click on Verifications on the left hand menu
3. Click on the Create Verification button
4. Share the session by copying the generated link

Cap on the session creation rate

Note that there is a maximum limit to how many sessions you can create in an integration based on your current Helium ID plan. If you require higher rate limits, please contact support.

---

Verification session statuses

The session status indicates the progress of the verification session, signaling the stage where the end-user’s verification process currently is.

Status	What does this mean?
not started	A session has been created for the end-user. They have not yet entered the verification flow.
started	The end-user has started their session and landed in the verification flow. No decision is available yet.
submitted	End-user’s required data has been submitted. No decision is available yet.
successful	Positive: end-user was verified. The verification process is complete.
failed	Negative: end-user has not been verified. The verification process is complete. If you decide to give the end-user another try, you need to create a new session using the POST /v1/verifications endpoint.
expired	Verification has been expired because the end-user never accessed the verification (a session expires 7 days after being created unless it gets a conclusive decision before that). If you decide to give the end-user another try, you need to create a new session using the POST /v1/verifications endpoint.
abandoned	Verification has been abandoned because the end-user started the verification session but never finished it (a session is abandoned 7 days after being created unless it gets a conclusive decision before that). If you decide to give the end-user another try, you need to create a new session using the POST /v1/verifications endpoint.
review	This status is issued whenever the automation engine could not issue a conclusive decision and the verification session needs to be reviewed by a human on your side. Note that in order to receive this status, it must be specifically configured and enabled for your integration.

---

About verification session expiry

All verification sessions expire after 7 days.

• Sessions in created status will move to expired
• Sessions in started status will move to abandoned