Webhook Payload Schemas

This page describes the webhook payloads Helium ID currently sends for verification events. All webhooks use the same outer envelope:

{
  "event": "verification.successful",
  "data": {}
}

Common headers

Helium ID signs webhook requests with these headers:

Webhook-Timestamp
Webhook-Signature

For signature validation details, see HMAC Authentication and Endpoint Security.

Individual verification payloads

These payloads apply to sessions created with POST /v1/verifications.

`verification.started`

Field	Type	Required	Notes
`verificationId`	string	Yes	Internal verification record ID.
`status`	string	Yes	Current status, currently `started`.
`statusCode`	number	Yes	Numeric status code, currently `2000`.
`vendorData`	string	No	Your correlation value if supplied at creation time.

`verification.selfie_uploaded`

Field	Type	Required	Notes
`verificationId`	string	Yes	Internal verification record ID.
`selfieKey`	string	No	Storage key for the uploaded selfie.
`vendorData`	string	No	Your correlation value if supplied.

`verification.document_front_uploaded`

Field	Type	Required	Notes
`verificationId`	string	Yes	Internal verification record ID.
`documentType`	string	Yes	Document type selected in the flow.
`issuingState`	string	Yes	Document issuing country or state code.
`vendorData`	string	No	Your correlation value if supplied.

`verification.document_back_uploaded`

Field	Type	Required	Notes
`verificationId`	string	Yes	Internal verification record ID.
`documentType`	string	Yes	Document type stored on the verification.
`vendorData`	string	No	Your correlation value if supplied.

`verification.processing_started`

Field	Type	Required	Notes
`verificationId`	string	Yes	Internal verification record ID.
`vendorData`	string	No	Your correlation value if supplied.

`verification.biometrics_matched`

Field	Type	Required	Notes
`verificationId`	string	Yes	Internal verification record ID.
`vendorData`	string	No	Your correlation value if supplied.

`verification.successful`

Field	Type	Required	Notes
`verificationId`	string	Yes	Internal verification record ID.
`vendorData`	string	No	Your correlation value if supplied.
`statusCode`	number	Yes	Numeric decision code, currently `2010`.
`docInfo`	object	Yes	Parsed document information.
`userSelfie`	string	No	URL for the stored selfie image.
`userIdBack`	string	No	URL for the back document image when available.
`userIdFront`	string	No	URL for the front document image.

`docInfo`

Field	Type	Required	Notes
`docType`	string	Yes	Document type.
`docNumber`	string	No	Extracted document number.
`issueDate`	string	No	Extracted issue date if available.
`expiryDate`	string	No	Extracted expiry date if available.
`issuingState`	string	No	Extracted issuing country or state.
`firstName`	string	No	Extracted first name.
`lastName`	string	No	Extracted last name.
`middleName`	string	No	Extracted middle name.
`dob`	string	No	Extracted date of birth.
`sex`	string	No	Extracted sex value.

`verification.failed`

Field	Type	Required	Notes
`verificationId`	string	Yes	Internal verification record ID.
`reason`	string	Yes	Failure reason stored on the verification.
`vendorData`	string	No	Your correlation value if supplied.
`statusCode`	number	Yes	Numeric decision code, currently `4100`.

Company verification payloads

These payloads apply to sessions created with POST /v1/company-verifications.

Shared company fields

Most company-verification webhook events include this common shape:

Field	Type	Required	Notes
`companyVerificationId`	string	Yes	Internal company-verification record ID.
`verificationId`	string	Yes	Public company verification ID. This matches the `verificationId` returned by the create response.
`externalId`	string	Yes	Public company verification ID, for example `cv_...`.
`vendorData`	string	No	Your correlation value if supplied.
`status`	string	Yes	Current company-verification status.
`reason`	string	No	Rejection reason or empty string.
`submittedAt`	string	No	ISO timestamp for submission when available.
`campaignId`	string	No	Campaign identifier if the verification was created from a campaign.
`campaignVersion`	number	No	Campaign version if available.
`companyProfile`	object	Yes	Normalized company/customer data intended for downstream integrations such as account-opening and banking providers. Nested fields may still be empty when the data has not been collected or confirmed yet.
`review`	object	Yes	Readiness and review metadata that explains how complete or review-dependent the profile currently is.

`companyProfile`

companyProfile gives you the best currently available company-customer data in a stable, integration-friendly shape.

`companyProfile.business`

Field	Type	Required	Notes
`legalName`	string	No	Company legal name.
`tradingName`	string	No	Trading or operating name when available.
`registrationNumber`	string	No	Company registration number, for example RC number.
`registrationType`	string	No	Business or registration type.
`countryOfRegistration`	string	No	Country of incorporation or registration.
`dateOfRegistration`	string	No	Registration date when available.
`businessBvn`	string	No	Business-level BVN when it is explicitly collected or confirmed. This is distinct from person-level officer BVNs.
`taxId`	string	No	Tax identifier or TIN where available.
`industry`	string	No	Industry or sector.
`description`	string	No	Business activity or description.
`website`	string	No	Business website.

`companyProfile.contact`

Field	Type	Required	Notes
`emails.general`	string	No	Primary company email.
`emails.alternate`	string	No	Alternate company email when available.
`emails.representative`	string	No	Representative email.
`phoneNumbers.general`	string	No	Primary business phone number.
`phoneNumbers.alternate`	string	No	Alternate business phone number.
`phoneNumbers.representative`	string	No	Representative phone number.
`addresses.operating`	object	No	Operating address.
`addresses.registered`	object	No	Registered address.
`addresses.representativeResidential`	object	No	Representative residential address when captured.

`companyProfile.authorisedRepresentative`

Field	Type	Required	Notes
`firstName`	string	No	Representative first name.
`middleName`	string	No	Representative middle name.
`lastName`	string	No	Representative surname.
`fullName`	string	No	Representative full name.
`email`	string	No	Representative email.
`phoneNumber`	string	No	Representative phone number.
`nationality`	string	No	Representative nationality.
`countryOfResidence`	string	No	Representative country of residence.
`relationshipToBusiness`	string	No	Role or relationship to the business.
`isAuthorised`	string	No	Whether the representative states they are authorised.
`ownsPartOfBusiness`	string	No	Whether the representative states they own part of the business.
`shareholdingPercentage`	string	No	Shareholding percentage when declared.
`identityDocumentType`	string	No	Representative ID type.
`documentNumber`	string	No	Representative document number.
`issuingCountry`	string	No	ID issuing country.
`expiryDate`	string	No	ID expiry date.
`dateOfBirth`	string	No	Date of birth.
`residentialAddress`	object	No	Residential address or best available address string.

`companyProfile.officers`

Each officer entry can include:

Field	Type	Required	Notes
`firstName`	string	No	Officer first name.
`middleName`	string	No	Officer middle name.
`lastName`	string	No	Officer surname.
`fullName`	string	No	Officer full name.
`email`	string	No	Officer email.
`phoneNumber`	string	No	Officer phone number.
`role`	string	No	Normalized role such as `director`, `owner`, or `authorised_representative`.
`roles`	string[]	No	Additional normalized roles when applicable.
`rawRole`	string	No	Original self-declared role text where available.
`nationality`	string	No	Officer nationality.
`countryOfResidence`	string	No	Officer country of residence.
`shareholdingPercentage`	string	No	Ownership share or declared allocation.
`identityDocumentType`	string	No	Officer ID type.
`documentNumber`	string	No	Officer document number.
`issuingCountry`	string	No	ID issuing country.
`expiryDate`	string	No	ID expiry date.
`dateOfBirth`	string	No	Date of birth.
`bvn`	string	No	BVN when captured.
`address`	object	No	Best available structured or full-text address.
`source`	string	No	Current source of the officer row, for example `self_reported`.

`companyProfile.ownership`

Field	Type	Required	Notes
`threshold`	number	No	Beneficial ownership threshold used for derivation.
`shareholders`	object[]	No	Shareholder rows from the ownership profile.
`directors`	object[]	No	Director rows from the ownership profile.
`beneficialOwners`	object[]	No	Derived beneficial owners based on the ownership profile.
`unresolvedCorporateOwners`	string[]	No	Material corporate owners that may still need deeper beneficial-owner lookthrough.

`companyProfile.authority`

Field	Type	Required	Notes
`role`	string	No	Role declared in the authority section.
`isAuthorised`	string	No	Whether authority has been declared.
`isDirector`	string	No	Whether the representative is a director.
`additionalSignatoryRequired`	string	No	Whether extra authority evidence is needed.
`livenessStatus`	string	No	Current liveness status.
`livenessVerificationId`	string	No	Linked individual liveness verification ID.
`livenessStartedAt`	string	No	Liveness start timestamp.
`livenessCompletedAt`	string	No	Liveness completion timestamp.

`companyProfile.additionalInformation`

Field	Type	Required	Notes
`purposeOfRelationship`	string	No	Declared purpose of relationship.
`expectedActivity`	string	No	Expected activity summary.
`expectedTransactionVolume`	string	No	Expected transaction volume.
`sourceOfFunds`	string	No	Source of funds.
`sourceOfWealth`	string	No	Source of wealth.
`countriesOfOperation`	string[]	No	Countries of operation.
`regulatoryStatus`	string	No	Regulatory status when provided.
`regulatoryLicences`	string	No	Regulatory licence information.

`companyProfile.documents`

Field	Type	Required	Notes
`provided`	object	No	Named document slots such as CAC, MEMART, Form 1, or proof of address.
`uploaded`	object[]	No	Uploaded document descriptors including file name, type, key, URL, and upload time where available.

`review`

The review block helps downstream consumers understand whether the payload is ready for provisioning or still needs more verification/review.

Field	Type	Required	Notes
`source`	string	No	High-level source of the current profile, for example `self_reported`, `document_enriched`, or `mixed`.
`analysisStatus`	string	No	Current document-analysis status.
`currentStage`	string	No	Current analysis stage when available.
`provider`	string	No	Analysis provider name when available.
`pendingInternalReview`	boolean	No	Whether the company verification is still awaiting review work.
`missingFields`	string[]	No	Important fields still missing from the normalized profile.
`reviewFlags`	string[]	No	Review flags raised by normalization or document analysis.
`followUp`	object	No	Additional follow-up guidance such as missing evidence, blocking fields, or requested documents.
`provisioning`	object	No	Quick readiness summary for downstream provisioning use cases.

`review.provisioning`

Field	Type	Required	Notes
`ready`	boolean	No	`true` when the profile is currently considered ready for downstream provisioning.
`pendingFields`	string[]	No	Important business, representative, or officer data points still missing.

`company_verification.submitted`

Uses the shared company fields and includes the normalized companyProfile and review blocks.

`company_verification.under_review`

Uses the shared company fields.

`company_verification.successful`

Uses the shared company fields and includes the normalized companyProfile and review blocks. This event uses the same normalized payload shape as company_verification.submitted. The difference is that the values now describe the successful outcome, including status: "successful" and the corresponding review/provisioning state.

`company_verification.failed`

Uses the shared company fields. For failed decisions, reason should contain the rejection reason.

`company_verification.liveness_completed`

Includes the shared company fields plus:

Field	Type	Required	Notes
`livenessVerificationId`	string	Yes	Linked individual verification ID used for the liveness step.
`userSelfie`	string	No	URL for the uploaded selfie captured during liveness.

Stability notes

Helium ID may add new optional fields to webhook payloads over time. Your webhook consumer should:

ignore unknown fields safely
handle new event types without crashing
store the raw payload for auditing and replay

For compatibility guidance, see Backwards Compatible Changes.

Getting started

Verifications

Company Verifications

Technical Guides

Reference

Common headers

Individual verification payloads

`verification.started`

`verification.selfie_uploaded`

`verification.document_front_uploaded`

`verification.document_back_uploaded`

`verification.processing_started`

`verification.biometrics_matched`

`verification.successful`

`docInfo`

`verification.failed`

Company verification payloads

Shared company fields

`companyProfile`

`companyProfile.business`

`companyProfile.contact`

`companyProfile.authorisedRepresentative`

`companyProfile.officers`

`companyProfile.ownership`

`companyProfile.authority`

`companyProfile.additionalInformation`

`companyProfile.documents`

`review`

`review.provisioning`

`company_verification.submitted`

`company_verification.under_review`

`company_verification.successful`

`company_verification.failed`

`company_verification.liveness_completed`

Stability notes

​Common headers

​Individual verification payloads

​verification.started

​verification.selfie_uploaded

​verification.document_front_uploaded

​verification.document_back_uploaded

​verification.processing_started

​verification.biometrics_matched

​verification.successful

​docInfo

​verification.failed

​Company verification payloads

​Shared company fields

​companyProfile

​companyProfile.business

​companyProfile.contact

​companyProfile.authorisedRepresentative

​companyProfile.officers

​companyProfile.ownership

​companyProfile.authority

​companyProfile.additionalInformation

​companyProfile.documents

​review

​review.provisioning

​company_verification.submitted

​company_verification.under_review

​company_verification.successful

​company_verification.failed

​company_verification.liveness_completed

​Stability notes

Common headers

Individual verification payloads

`verification.started`

`verification.selfie_uploaded`

`verification.document_front_uploaded`

`verification.document_back_uploaded`

`verification.processing_started`

`verification.biometrics_matched`

`verification.successful`

`docInfo`

`verification.failed`

Company verification payloads

Shared company fields

`companyProfile`

`companyProfile.business`

`companyProfile.contact`

`companyProfile.authorisedRepresentative`

`companyProfile.officers`

`companyProfile.ownership`

`companyProfile.authority`

`companyProfile.additionalInformation`

`companyProfile.documents`

`review`

`review.provisioning`

`company_verification.submitted`

`company_verification.under_review`

`company_verification.successful`

`company_verification.failed`

`company_verification.liveness_completed`

Stability notes