Create 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:

Send the verification object to https://server.heliumid.io/api/v1/verifications (*required)
Include the Content-Type: application/json header (*required)
Include the x-api-key header containing your integration’s API key (*required)
Include the vendorData parameter (strongly recommended for identifying the session on your end)
Optionally include the meta parameter to pass additional custom data
Optionally specify the method as auto (default, uses automated systems) or manual (reviewed by an Identity Specialist)
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 -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"
    }
}'

fetch("https://server.heliumid.io/api/v1/verifications", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    vendorData: "user_12345",
    method: "auto",
    meta: {
      key: "value",
    },
  }),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));

import requests
import json

url = "https://server.heliumid.io/api/v1/verifications"

payload = json.dumps({
  "vendorData": "user_12345",
  "method": "auto",
  "meta": {
    "key": "value"
  }
})
headers = {
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {
  url := "https://server.heliumid.io/api/v1/verifications"
  payload := strings.NewReader(`{"vendorData":"user_12345","method":"auto","meta":{"key":"value"}}`)

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("x-api-key", "YOUR_API_KEY")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://server.heliumid.io/api/v1/verifications"))
        .header("Content-Type", "application/json")
        .header("x-api-key", "YOUR_API_KEY")
        .method("POST", HttpRequest.BodyPublishers.ofString("{\"vendorData\":\"user_12345\",\"method\":\"auto\",\"meta\":{\"key\":\"value\"}}"))
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());

    System.out.println(response.body());
  }
}

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.

Go to your Helium Id Dashboard
Click on Verifications on the left hand menu
Click on the Create Verification button
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

Getting started

Verifications

Company Verifications

Technical Guides

Reference

Create with POST /verifications call

Before you start:

For API

Sample request

Sample response

Create Manually

Cap on the session creation rate

Verification session statuses

About verification session expiry

​Create with POST /verifications call

​Before you start:

​For API

​Sample request

​Sample response

​Create Manually

​Cap on the session creation rate

​Verification session statuses

​About verification session expiry

Create with POST /verifications call

Before you start:

For API

Sample request

Sample response

Create Manually

Cap on the session creation rate

Verification session statuses

About verification session expiry