Create verification session

An individual verification session is the standard way to send an end-user into Helium ID’s hosted identity flow. This page shows you how to create the session and what to do with the response.

Create with `POST /v1/verifications`

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.
Configure your webhook URLs if you want automated progress and decision updates.

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-user 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
}

What to do with the response

After creating a verification:

Store data.verificationId on your side
Redirect the end-user to data.link
Wait for webhooks or fetch the session later with:
- GET /v1/verifications
- GET /v1/verifications/{id}

For field-by-field webhook payload definitions, see Webhook Payload Schemas.

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 current state of the individual verification.

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 terminal 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.
`cancelled`	The verification session was explicitly cancelled before it could be completed. The user cannot continue with that session.

Depending on your workflow, you may also see compatibility states such as completed or abandoned in some records or internal tooling. For integration logic, the important terminal outcomes are successful, failed, and cancelled.

How updates are delivered

Helium ID can notify your integration in two ways:

Events webhook for progress updates such as:
- verification.started
- verification.selfie_uploaded
- verification.document_front_uploaded
- verification.document_back_uploaded
- verification.processing_started
- verification.biometrics_matched
Decision webhook for terminal outcomes:
- verification.successful
- verification.failed

If you prefer to poll instead of listening for webhooks, use the public fetch endpoints.

Getting started

Verifications

Company Verifications

Technical Guides

Reference

Create with `POST /v1/verifications`

Before you start:

For API

Sample request

Sample response

What to do with the response

Create Manually

Cap on the session creation rate

Verification session statuses

How updates are delivered

​Create with POST /v1/verifications

​Before you start:

​For API

​Sample request

​Sample response

​What to do with the response

​Create Manually

​Cap on the session creation rate

​Verification session statuses

​How updates are delivered

Create with `POST /v1/verifications`

Before you start:

For API

Sample request

Sample response

What to do with the response

Create Manually

Cap on the session creation rate

Verification session statuses

How updates are delivered