Individual Entity Onboarding

Automate your KYC compliance workflows with BNDRY's Individual Entity Onboarding 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 Onboarding automation enables you to:

• Embed KYC workflows into your customer acquisition flow
• Collect customer data through customizable forms
• Transform form responses into structured entities
• Verify customer identities through integrated IDV providers
• Screen for PEP and sanctions through integrated compliance providers
• Receive real-time notifications when onboarding completes

How It Works

The onboarding automation creates a seamless three-way interaction between your business, your customers, and BNDRY's platform:

1. Your business initiates onboarding 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, transforming data into structured entities and performing identity verification and compliance screening
4. Your business receives webhook notifications when the process completes, enabling you to proceed with customer activation

Getting Started

Quick Start Checklist

Before you begin implementing the individual onboarding automation:

What BNDRY Configures During Onboarding

BNDRY works with you during platform onboarding to configure your individual entity onboarding automation and form definitions. Most customers need only one automation configuration, but we can set up multiple configurations for advanced use cases with specific requirements.

Each onboarding automation combines:

• Form definition - for data collection from your customers
• JSONata expression - to transform form responses into Individual entities
• Webhook URI - for notifications when onboarding completes

What You Do Once Live

Once configured, you'll primarily use the RunOnboardIndividualEntityJob API to execute the onboarding 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

Onboarding Job API Resource

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

The resource contains:

• name - Resource identifier
• form_definition - Reference to the FormKit schema for data collection
• jsonata_expression - JSONata expression to transform form response into IndividualEntity
• webhook_uri - Webhook target URI for notifications
• create_time and update_time - Resource timestamps

Form Definitions

Form definitions use FormKit schema to define the structure of your data collection forms. BNDRY will build these form definitions as part of your platform onboarding.

Example FormKit Schema

{
  "$cmp": "FormKit",
  "props": {
    "type": "form",
    "plugins": ["bndry-validation"],
    "actions": false
  },
  "children": [
    {
      "$cmp": "FormKit",
      "props": {
        "type": "text",
        "name": "firstName",
        "label": "First Name",
        "validation": "required|length:1,50"
      }
    },
    {
      "$cmp": "FormKit",
      "props": {
        "type": "date",
        "name": "dateOfBirth",
        "label": "Date of Birth",
        "validation": "required|min_age:18"
      }
    },
    {
      "$cmp": "FormKit",
      "props": {
        "type": "file",
        "name": "idDocument",
        "label": "Government ID",
        "validation": "required|file_type:pdf,jpg,png|max_size:5MB"
      }
    }
  ]
}

Data Transformation with JSONata

JSONata expressions transform form responses into Individual entities that populate your Risk Hub. The transformation maps form fields to the structured entity format defined in the BNDRY entity schema.

Example Transformation

{
  "individual": {
    "given_name": formResponse.firstName,
    "family_name": formResponse.lastName,
    "birth_date_time": formResponse.dateOfBirth,
    "nationality": formResponse.nationality,
    "occupation": formResponse.occupation,
    "government_id": {
      "passport": {
        "number": formResponse.idDocument.number,
        "issuer": formResponse.idDocument.issuer,
        "region_code": formResponse.idDocument.regionCode,
        "expiry_date_time": formResponse.idDocument.expiryDate
      }
    }
  },
  "contact_info": {
    "email_address": [formResponse.email],
    "telephone": [formResponse.phone],
    "residential_addresses": [{
      "address_lines": [formResponse.address.street],
      "locality": formResponse.address.city,
      "region_code": formResponse.address.country,
      "postal_code": formResponse.address.postalCode
    }]
  }
}

For more advanced transformation patterns and JSONata syntax, see the JSONata documentation.

You can test JSONata expressions using the JSONata Exerciser before implementing them in your automation.

Entity Annotations

Entity annotations are optional key-value pairs that you can attach to entities during onboarding. The primary use case is linking BNDRY entities back to your internal systems - when you receive webhook notifications about entities, you can use these annotations to tie them back to your CRM or internal records.

Common annotation patterns include:

• System integration (e.g., "external_id": "cust_98765", "crm_customer_id": "SF-001234", "source_system": "salesforce")
• Regulatory context (e.g., "jurisdiction": "AU", "onboarding_channel": "digital", "reporting_entity": "subsidiary-a")
• Business context (e.g., "account_manager": "jane.smith", "relationship_type": "corporate", "due_diligence_level": "enhanced")

Annotations are stored with the entity in your Risk Hub and are included in webhook notifications, enabling seamless integration between BNDRY and your existing systems. They follow the Google API annotation pattern and are completely optional.

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://bndry.app/api/v1alpha/entities/-/onboardIndividualEntityJobs/default:run \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "redirectUri": "http://example.com",
    "entityAnnotations": {
      "property1": "string",
      "property2": "string"
    }
  }'

{
  "error": {
    "code": 0,
    "message": "string",
    "details": [ … ]
  },
  "name": "string",
  "metadata": {
    "type": "string",
    "value": "string",
    "debug": {}
  },
  "done": true
}

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

{
  "name": "operations/op_abc123",
  "metadata": {
    "redirect_uri": "https://bndry.net/onboarding/session_xyz789"
  },
  "done": false
}

Monitoring Operation Progress

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

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

{
  "error": {
    "code": 0,
    "message": "string",
    "details": [ … ]
  },
  "name": "string",
  "metadata": {
    "type": "string",
    "value": "string",
    "debug": {}
  },
  "done": true
}

Handling Completion Notifications

app.post("/webhooks/onboarding-complete", (req, res) => {
  const webhookPayload = req.body;

  // Process the webhook payload according to the format
  // provided during your BNDRY platform onboarding

  // Update your customer records and trigger downstream processes

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

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

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

This returns the event data with references to the created entity:

{
  "success": true,
  "entity_created": true,
  "identity_verification_status": "passed",
  "sanctions_screening_status": "clear",
  "related_ref": "entities/entity-abc123",
  "related_ref_url": "/v1alpha/entities/entity-abc123",
  "entity_annotations": {
    "external_id": "cust_98765",
    "crm_customer_id": "SF-001234",
    "jurisdiction": "AU"
  }
}

Accessing the Created Entity

You can then fetch the complete entity details:

curl -i -X GET \
  https://bndry.app/api/v1alpha/entities/entity-abc123 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

{
  "company": {
    "type": "COMPANY_TYPE_UNSPECIFIED",
    "industry": "string"
  },
  "name": "string",
  "displayName": "string",
  "contactInfo": {
    "telephone": [ … ],
    "businessTelephone": [ … ],
    "emailAddress": [ … ],
    "primaryContact": [ … ],
    "website": [ … ],
    "registeredBusinessAddresses": [ … ],
    "principalBusinessAddresses": [ … ],
    "residentialAddresses": [ … ]
  },
  "registration": {
    "property1": { … },
    "property2": { … }
  },
  "riskDetails": {
    "riskStatus": "RISK_STATUS_UNSPECIFIED",
    "riskStatusReason": "RISK_STATUS_REASON_UNSPECIFIED",
    "riskRating": "RISK_RATING_UNSPECIFIED"
  },
  "entityRelationships": [
    { … }
  ],
  "createTime": "1s",
  "updateTime": "1s",
  "purgeTime": "1s",
  "annotations": {
    "property1": "string",
    "property2": "string"
  },
  "etag": "string"
}

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://bndry.app/api${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 Onboarding automation, contact the BNDRY team during your platform onboarding process.

Ready to automate your individual entity onboarding? Get started with BNDRY's Early Access Program