Individual Entity Verification In-Built Automation

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Automate your KYC compliance workflows with BNDRY's Individual Entity Verification automation. Create configurable workflows that collect customer data, verify identities, screen for PEP and sanctions, and create structured entities in your Risk Hub—all without manual intervention.

Overview

The Individual Entity Verification automation enables you to:

• Verify customer identities through integrated IDV providers
• Receive real-time notifications when onboarding completes

How It Works

The Individual Entity Verification automation is designed to conduct ID Validation on existing entities in your Risk Hub. The process involves:

1. Your business initiates verification by running a pre-configured job for each customer
2. Your customer is redirected to BNDRY's hosted data collection forms to provide their information
3. BNDRY's platform handles the complete verification workflow, performing identity verification and compliance screening
4. Your business receives webhook notifications when the process completes, enabling you to utilise the result in real time
5. Your customer is redirected seamlessly back into your workflow to continue their journey

Getting Started

Quick Start Checklist

Before you begin implementing the individual onboarding automation:

What You Do Once Live

Once configured, you'll primarily use the RunIndividualEntityVerificationJob API to execute the verification automation and monitor progress through the long-running operations API.

For testing and development, you can use the mock server to experiment with the API without affecting production data.

Core Concepts

Verification Job API Resource

The RunIndividualEntityVerificationJob API resource represents an automation for verifying individual entities through data capture, entity creation, and verification workflows.

The resource contains:

• name - Resource identifier
• entity_resource_name - Target entity in your Risk Hub
• webhook_uri - Webhook target URI for notifications
• create_time and update_time - Resource timestamps

Using the API

Authentication

Before making API calls, you'll need to authenticate using OAuth 2.0 Client Credentials flow. See the Authentication guide for complete details on obtaining and using access tokens.

Running the Onboarding Automation

Once your automation is configured, you can run it for each customer:

curl -i -X POST \
  https://api.bndry.app/v1alpha/individualEntityVerificationJobs/your_verification_job_id:run \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityResourceName": "entities/john-smith-001",
    "redirectUri": "https://app.example.com/verification/complete"
  }'

This returns a long-running operation with the redirect URI in the metadata:

{
  "name": "operations/op_abc123",
  "metadata": {
    "redirect_uri": "https://forms.bndry.net/verifications/{your_verification_job_id}/op_abc123"
  },
  "done": false
}

Hosted or embedded experience?

You can choose to redirect your customers to BNDRY's hosted data collection forms using the provided redirect_uri, or embed the forms directly within your application using an iframe. For embedding, check out our dedicated guide to Embedding BNDRY Forms.

Monitoring Operation Progress

You can monitor the progress of the onboarding operation by polling the operation status:

curl -i -X GET \
  https://api.bndry.app/v1alpha/individualEntityVerificationJobs/your_verification_job_id/operations/op_abc123 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Error Handling

The onboarding process can fail for various reasons (form abandonment, verification failures, etc.). Failed operations will have done: true with error details in the error field. See the Errors guide for complete error handling patterns.

API Reference

Primary APIs

Once your onboarding automation is configured, you'll primarily use these APIs:

For complete API documentation including request/response schemas, see the API Reference.

Webhook Configuration

How BNDRY Webhooks Work

BNDRY webhooks follow the CloudEvents specification and use the dataref extension, also known as the "Claim Check Pattern". Instead of including sensitive event data directly in webhook payloads, BNDRY provides a reference URL where you can securely fetch the actual event data.

This two-step process works as follows:

1. Receive webhook notification: You get a "thin" CloudEvent containing only metadata and a dataref URL
2. Fetch complete event data: Make an authenticated API call using the dataref to retrieve the full event details

This approach provides several key benefits:

• Security: Prevents accidental exposure of personally identifiable information (PII) in webhook payloads
• Access control: BNDRY can verify that the webhook receiver has proper permissions before releasing sensitive data
• Reduced payload size: Webhook payloads remain lightweight regardless of the underlying event data size
• Audit trail: All access to sensitive event data can be logged and monitored

Events delivered by this automation

Authentication

BNDRY webhooks use a combination of signing verification and OAuth2.0 Bearer token authentication:

{
  "url": "https://example.com/webhook",
  "signing_secret": "your-signing-secret",
  "authentication": {
    "type": "bearer",
    "value": "your-bearer-token"
  }
}

Webhook Payload Format

When an individual entity's identity verification completes, you'll receive a CloudEvents-formatted webhook payload:

{
  "specversion": "1.0",
  "type": "bndry.api.risk.entities.v1alpha.IdentityVerificationCompleted",
  "source": "api.bndry.net/Entity/entities/entity-abc123",
  "id": "event-12345-67890",
  "datacontenttype": "application/json",
  "dataref": "/v1alpha/entities/entity-abc123/events/event-12345-67890",
  "time": "2024-01-15T10:30:00Z"
}

Retrieving Event Data

To get the complete event details, make an authenticated request to the URL provided in the dataref field:

GET /v1alpha/entities/entity-abc123/events/event-12345-67890
Authorization: Bearer your-api-token

Complete Webhook Handler Example

Here's a complete webhook handler implementation:

const crypto = require("crypto");

app.post("/webhooks/onboarding-complete", async (req, res) => {
  try {
    // Verify webhook signature
    const signature = req.headers["x-bndry-signature"];
    const expectedSignature = crypto
      .createHmac("sha256", process.env.BNDRY_SIGNING_SECRET)
      .update(JSON.stringify(req.body))
      .digest("hex");

    if (signature !== `sha256=${expectedSignature}`) {
      return res.status(401).send("Invalid signature");
    }

    const cloudEvent = req.body;

    // Fetch the complete event data
    const eventResponse = await fetch(
      `https://api.bndry.app${cloudEvent.dataref}`,
      {
        headers: {
          Authorization: `Bearer ${process.env.BNDRY_API_TOKEN}`,
          "Content-Type": "application/json",
        },
      }
    );

    const eventData = await eventResponse.json();

    // Process the onboarding completion
    if (eventData.success && eventData.entity_created) {
      // Update your customer records
      await updateCustomerRecord(eventData.entity_annotations.external_id, {
        bndryEntityId: eventData.related_ref,
        onboardingStatus: "completed",
        identityVerified: eventData.identity_verification_status === "passed",
        sanctionsCleared: eventData.sanctions_screening_status === "clear",
      });

      // Trigger downstream processes
      await activateCustomerAccount(eventData.entity_annotations.external_id);
    }

    res.status(200).send("OK");
  } catch (error) {
    console.error("Webhook processing error:", error);
    res.status(500).send("Internal Server Error");
  }
});

Webhook URL Requirements

Webhook URLs must meet these security requirements:

• HTTPS only - HTTP URLs are not permitted
• Valid hostname - Must have a proper host component
• No private/internal IPs - Cannot target private, loopback, link-local, or multicast IP addresses
• Domain restrictions - Cannot target blocked domains including:
  • bndry.app and bndry.net (prevents self-targeting)
  • Cloud metadata services (metadata.google.internal, metadata.google.com, metadata.azure.com)

During webhook execution, DNS resolution is validated to ensure hostnames don't resolve to blocked IP addresses.

Support

For questions about implementing the Individual Entity Verification automation, contact the BNDRY team during your platform onboarding process.

Ready to embed ID verification into your processes? Get started with BNDRY's Early Access Program