Skip to main content

​
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 -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.
StatusWhat does this mean?
not startedA session has been created for the end-user. They have not yet entered the verification flow.
startedThe end-user has started their session and landed in the verification flow. No decision is available yet.
submittedEnd-user’s required data has been submitted. No decision is available yet.
successfulPositive: end-user was verified. The verification process is complete.
failedNegative: 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.
expiredVerification 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.
abandonedVerification 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.
reviewThis 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