> ## 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. # Webhook Payload Schemas > Field-by-field reference for Helium ID webhook payloads across individual and company verification events. This page describes the webhook payloads Helium ID currently sends for verification events. All webhooks use the same outer envelope: ```json theme={null} { "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](/technical/hmac). ## 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](/technical/backwards-compatibility).