Recipe: Company Verification Integration

​

What you will build

1. Create a company verification from your server
2. Store the public company verification ID
3. Send the representative to the hosted link
4. Handle progress and decision webhooks
5. Reconcile the result in your own system

​

Step 1: Create the company verification

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": "app_67890"
    }
  }'

• data.verificationId as the public company verification ID
• data.link
• your own vendorData

​

Step 2: Send the representative to the hosted flow

• processId for the internal company verification ID
• hostedToken for secure access to the hosted flow

​

Step 3: Listen for company webhooks

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

• company_verification.successful
• company_verification.failed

​

Step 4: Reconcile IDs correctly

• create-response verificationId = public company verification ID
• webhook companyVerificationId = internal company verification ID
• webhook externalId = public company verification ID

​

Step 5: Apply review logic

• when you receive company_verification.submitted, mark the case as awaiting review
• when you receive company_verification.under_review, mark the case as in review
• when you receive company_verification.successful, mark the business as approved
• when you receive company_verification.failed, mark the business as rejected and store the reason

​

Environment behavior

• in test, customer admins can move company verifications through review and terminal states for integration testing
• in live, Helium ID controls final terminal decisions

​

Minimal Node.js handler example

app.post("/webhooks/helium", express.raw({ type: "*/*" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  const event = JSON.parse(rawBody);

  if (event.event === "company_verification.submitted") {
    const { externalId, vendorData } = event.data;
    // Mark the business case as submitted
  }

  if (event.event === "company_verification.successful") {
    const { externalId, vendorData } = event.data;
    // Mark the business as approved
  }

  if (event.event === "company_verification.failed") {
    const { externalId, vendorData, reason } = event.data;
    // Mark the business as rejected
  }

  res.status(200).send("ok");
});

​

Recommended stored fields

• public verificationId from the create response
• internal companyVerificationId when it first arrives by webhook
• externalId
• vendorData
• current status
• latest webhook event
• raw webhook payload
• environment used