Create Company Verification

• how to create a company verification session
• how to use the returned hosted link correctly
• what the representative completes in the hosted flow
• how to track progress and outcomes after submission

​

Before you start

• Create an API key in the Helium ID Dashboard.
• Make this request from your server. Do not expose your API key in browser or mobile-app code.
• Configure your API key’s webhook URLs if you want automated updates.
• Keep the returned hosted link intact. The link includes a secure hosted-flow token and must be used exactly as returned.

​

Create a company verification

POST /v1/company-verifications

​

Request headers

​

Request body

​

Example request

curl -X POST 'https://server.heliumid.io/api/v1/company-verifications' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "vendorData": "business_12345",
    "meta": {
      "applicationId": "application_67890"
    },
    "campaignId": "cmp_64ff2f3f4f31d4d5f2ab1234"
  }'

const response = await fetch(
  "https://server.heliumid.io/api/v1/company-verifications",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.HELIUM_ID_API_KEY,
    },
    body: JSON.stringify({
      vendorData: "business_12345",
      meta: { applicationId: "application_67890" },
      campaignId: "cmp_64ff2f3f4f31d4d5f2ab1234",
    }),
  }
)

const result = await response.json()
console.log(result.data.link)
console.log(result.data.verificationId)

​

Example response

{
  "status": true,
  "message": "Created company verification",
  "data": {
    "link": "https://verify.heliumid.io/company?processId=69d4f7657bcbe3b58b96b2f7&hostedToken=eyJleGFtcGxlIjoidG9rZW4ifQ",
    "verificationId": "cv_0b5f6f4e0aab25d8c130ab21",
    "campaignId": "cmp_64ff2f3f4f31d4d5f2ab1234",
    "campaignVersion": 3,
    "expiresAt": "2026-08-25T12:00:00.000Z"
  },
  "code": 200
}

​

Understand the response

• data.link: the full hosted URL you should redirect the representative to
• data.verificationId: Helium ID’s public company-verification identifier, useful for your own tracking and webhook correlation

• processId: Helium ID’s internal company-verification record ID
• hostedToken: the secure token that authorizes the hosted session

​

Send the representative to the hosted flow

1. Upload company documents
2. Review AI-assisted extraction results
3. Confirm company details
4. Review ownership and control details
5. Complete the authorising-person section
6. Provide additional compliance information
7. Review and submit the company verification

​

Important: use the returned link exactly as-is

• Do not replace processId with vendorData, your own customer ID, or the public verificationId.
• Do not strip the hostedToken from the URL.
• Do not generate your own company-verification links on the client.

​

Tracking company verifications

1. webhooks
2. the Helium ID Dashboard

​

Webhook events

• company_verification.submitted
• company_verification.liveness_completed
• company_verification.under_review

• company_verification.successful
• company_verification.failed

​

Live vs test company verifications

• Live company verifications: final review and terminal decisions are handled by Helium ID.
• Test company verifications: customer admins can move the verification through review states in the dashboard for testing purposes.

​

Managing verifications

1. Log in to the Helium ID Dashboard
2. Open Verifications
3. Switch to the company-verifications view
4. Open the specific company verification to inspect its details, uploaded documents, progress, and current status