> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliumid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Company Verification Lifecycle

> Understand company verification statuses, webhook events, and how Helium ID moves a company verification from creation to final decision.

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:

1. You create a company verification with `POST /v1/company-verifications`
2. The representative opens the hosted link
3. The representative uploads documents, reviews extracted data, and submits the flow
4. Helium ID reviews the submission
5. 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:

```json theme={null}
{
  "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.