Company Verification Lifecycle

Company verifications can be followed through public fetch endpoints, dashboard review, and webhooks. The webhooks are still the most useful option when you want downstream systems to react automatically. This page explains the statuses and events you should expect.

How a company verification moves through the flow

The typical lifecycle looks like this:

You create a company verification with POST /v1/company-verifications
The representative opens the hosted link
The representative uploads documents, reviews extracted data, and submits the flow
Helium ID reviews the submission
Helium ID issues a final outcome

Company verification statuses

The company verification flow currently uses these statuses:

Status	What it means
`not started`	The company verification has been created, but the representative has not started the hosted flow yet.
`started`	The representative has entered the flow and is progressing through the hosted steps.
`submitted`	The representative has completed the hosted flow and submitted the company verification for review.
`under review`	The submission is being reviewed after it was submitted.
`successful`	Helium ID approved the company verification. This is a terminal outcome.
`failed`	Helium ID rejected the company verification. This is a terminal outcome.

In practice:

submitted means the representative finished their part
under review means a reviewer is now handling the case
successful and failed are the conclusive outcomes you should treat as final

Company verification webhook events

Company verification uses dedicated webhook event names so they can be handled separately from individual verification events.

Events webhook

The following events are sent to the API key’s events webhook URL:

company_verification.submitted
company_verification.liveness_completed
company_verification.under_review

These are progress events. They tell you that work is moving forward, but they are not final outcomes.

Decision webhook

The following events are sent to the API key’s decision webhook URL:

company_verification.successful
company_verification.failed

These are the terminal outcome events.

Payload shape

Company-verification webhook payloads are sent in the standard Helium ID wrapper:

{
  "event": "company_verification.submitted",
  "data": {
    "companyVerificationId": "69d4f7657bcbe3b58b96b2f7",
    "verificationId": "cv_0b5f6f4e0aab25d8c130ab21",
    "externalId": "cv_0b5f6f4e0aab25d8c130ab21",
    "vendorData": "business_12345",
    "status": "submitted",
    "reason": "",
    "submittedAt": "2026-08-18T12:00:00.000Z",
    "campaignId": "cmp_64ff2f3f4f31d4d5f2ab1234",
    "campaignVersion": 3,
    "companyProfile": {
      "business": {
        "legalName": "Acme Limited",
        "registrationNumber": "RC123456",
        "countryOfRegistration": "NGA",
        "businessBvn": "22334455667",
        "industry": "technology"
      },
      "authorisedRepresentative": {
        "fullName": "Jane Doe",
        "email": "jane@acme.example",
        "relationshipToBusiness": "Director"
      },
      "officers": [
        {
          "fullName": "Jane Doe",
          "role": "director"
        }
      ]
    },
    "review": {
      "source": "mixed",
      "pendingInternalReview": true,
      "provisioning": {
        "ready": false,
        "pendingFields": []
      }
    }
  }
}

The important change is that company-verification events include a normalized companyProfile block and a review block. That shape is designed to help downstream systems, including bank-account or business-customer providers, consume the important company details in a stable shape. The example above uses company_verification.submitted, but company_verification.successful uses the same normalized payload shape as well. In practice, the event, status, and review/readiness values change to reflect the successful outcome, while the top-level structure and the normalized companyProfile and review blocks remain the same. Those fields may come from:

data entered directly in the hosted flow
document extraction and normalization
future internal review enrichment

The review block helps you interpret how ready the payload currently is, especially when some nested fields still depend on review or follow-up evidence.

Live vs test company verifications

There is an important difference between live and test company verifications:

Live company verifications: Helium ID controls terminal decisions.
Test company verifications: customer admins can move the verification through review states in the dashboard to test integrations and webhook handling.

If your integration is listening for company webhooks, treat live and test traffic the same way on your side, but make sure your business logic knows whether the source API key is live or test.

What to store on your side

For reliable correlation, store at least:

your own internal business or application ID in vendorData
the returned verificationId from the create response
the webhook data.companyProfile if you plan to provision downstream business accounts
the webhook event
the webhook data.status

That gives you enough information to match each update to the correct company verification in your system.

Getting started

Verifications

Company Verifications

Technical Guides

Reference

How a company verification moves through the flow

Company verification statuses

Company verification webhook events

Events webhook

Decision webhook

Payload shape

Live vs test company verifications

What to store on your side

​How a company verification moves through the flow

​Company verification statuses

​Company verification webhook events

​Events webhook

​Decision webhook

​Payload shape

​Live vs test company verifications

​What to store on your side

How a company verification moves through the flow

Company verification statuses

Company verification webhook events

Events webhook

Decision webhook

Payload shape

Live vs test company verifications

What to store on your side