Beetlelabs

Beetlelabs API Documentation

Welcome to the Beetlelabs API Documentation, your comprehensive guide to integrating with Beetlelabs' powerful verification and risk assessment platform. Our API provides a robust set of tools for Know Your Business (KYB), Know Your Customer (KYC), and compliance processes, enabling seamless integration into your applications for business and individual verification workflows.

Introduction

The Beetlelabs API is designed to streamline verification processes, including risk assessments, personal details management, Ultimate Beneficial Owner (UBO) verification, director management, business document handling, liveness checks, and more. Built with scalability and ease of use in mind, our API supports a wide range of use cases, from onboarding clients to managing compliance data.

This documentation provides an overview of all available endpoints, organized by functionality, along with example requests to help you get started quickly. Whether you're performing risk assessments, managing verification sessions, or retrieving business documents, the Beetlelabs API offers flexible and secure solutions.

API Overview

The Beetlelabs API is structured around RESTful principles, using JSON for data exchange. All endpoints are accessible under the base path /beetlelabs-verification. Key features include:

• Risk Assessment (KYB): Create, update, and retrieve risk assessments for businesses, including scores for ownership structure, AML, location, and transaction risks.

• Personal Details (KYC): Manage individual details, including residential address, occupation, and verification status.

• Ultimate Beneficial Owners (UBOs): Handle UBO data, including identity verification and ownership details.

• Directors: Manage director information, including positions and identification documents.

• Business Documents: Upload, retrieve, and update business-related documents like certificates of incorporation and tax registrations.

• Liveness Checks: Perform liveness verification to ensure user authenticity.

• Verification Sessions: Create and manage sessions for streamlined verification workflows.

• Third-Party Verification: Store and retrieve verification data from external sources.

Getting Started

To begin using the Beetlelabs API, ensure you have an API key and access to the base URL /beetlelabs-verification. Below are example snippets for some common operations.

Example: Create a Risk Assessment

Create a new KYB risk assessment for a business.

curl -X POST "https://api.beetlelabs.com/beetlelabs-verification/risk-rating/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "business_id": "987fcdeb-12ab-34cd-56ef-789012345678",
  "overall_risk_score": 75,
  "risk_level": "medium",
  "ownership_structure_score": 80,
  "aml_risk_score": 70,
  "location_risk_score": 65,
  "transaction_risk_score": 60
}'

Response:

{
  "id": "456e7890-f12c-34d5-a678-901234567890",
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "business_id": "987fcdeb-12ab-34cd-56ef-789012345678",
  "overall_risk_score": 75,
  "risk_level": "medium",
  "ownership_structure_score": 80,
  "aml_risk_score": 70,
  "location_risk_score": 65,
  "transaction_risk_score": 60,
  "created_at": "2025-05-21T13:01:00Z",
  "updated_at": "2025-05-21T13:01:00Z",
  "business": {},
  "session": {}
}

Example: Create Personal Details (KYC)

Submit personal details for KYC verification.

curl -X POST "https://api.beetlelabs.com/beetlelabs-verification/personal-details/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "client_id": 1,
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "occupation": "Software Engineer",
  "residential_address": "123 Main St, City, Country",
  "nationality": "US",
  "mobile_verification": false,
  "email_verification": false
}'

Response:

{
  "id": "789e0123-f45d-67e8-a901-234567890123",
  "client_id": 1,
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "occupation": "Software Engineer",
  "residential_address": "123 Main St, City, Country",
  "nationality": "US",
  "mobile_verification": false,
  "email_verification": false,
  "status": "pending",
  "risk_level": "unknown",
  "created_at": "2025-05-21T13:01:00Z",
  "updated_at": "2025-05-21T13:01:00Z"
}

API Endpoints

Below is a summary of the key endpoint categories and their functionalities. Explore the full documentation for detailed specifications.

Risk Assessment (Risk-Rating)

• POST /risk-rating/: Create a new KYB risk assessment.

• PATCH /risk-rating/{assessment_id}: Update an existing assessment.

• GET /risk-rating/session/{session_id}: Retrieve assessments by session ID.

• GET /risk-rating/session/{session_id}/latest: Fetch the latest assessment for a session.

• GET /risk-rating/session/{session_id}/history: Get the assessment history for a session.

• GET /risk-rating/{assessment_id}/context: Retrieve an assessment with additional context.

Personal Details (KYC)

• POST /personal-details/: Create new personal details.

• GET /personal-details/: List personal details with pagination and filtering.

• GET /personal-details/summary: Get a verification summary for a client.

• GET /personal-details/{details_id}: Retrieve specific personal details.

• PATCH /personal-details/{details_id}: Update personal details.

• DELETE /personal-details/{details_id}: Delete personal details.

Ultimate Beneficial Owners (UBOs)

• POST /ubos/: Create a new UBO record.

• GET /ubos/: List UBOs with pagination and filtering.

• GET /ubos/{ubo_id}: Retrieve a specific UBO.

• PUT /ubos/{ubo_id}: Update a UBO record.

• DELETE /ubos/{ubo_id}: Delete a UBO record.

Directors

• POST /directors/: Create a new director record.

• GET /directors/: List directors with pagination and filtering.

• GET /directors/{director_id}: Retrieve a specific director.

• PUT /directors/{director_id}: Update a director record.

• DELETE /directors/{director_id}: Delete a director record.

Business Documents

• POST /business-documents/: Upload a new business document.

• GET /business-documents/: List business documents with pagination and filtering.

• GET /business-documents/{document_id}: Retrieve a specific document.

• PUT /business-documents/{document_id}: Update a document.

• DELETE /business-documents/{document_id}: Delete a document.

ID and Address Document Proof

• POST /document-proof/id-documents/: Create a new ID document.

• GET /document-proof/id-documents/{document_id}: Retrieve an ID document.

• PATCH /document-proof/id-documents/{document_id}: Update an ID document.

• GET /document-proof/sessions/{session_id}/id-document: List ID documents for a session.

• POST /document-proof/address-proofs/: Create a new address proof.

• GET /document-proof/sessions/{session_id}/address-proofs: List address proofs for a session.

Liveness Checks

• POST /liveness/liveness-checks/: Create a new liveness check.

• GET /liveness/sessions/{session_id}/liveness-check: Retrieve liveness check for a session.

Business Details (KYB)

• GET /client_kybs/summary: Get a verification summary for KYB.

• GET /client_kybs/{client_id}/{session_id}: Retrieve customer details.

• GET /client_kybs/{client_id}: List customers for a client.

• POST /client_kybs/: Create a new client.

• PATCH /client_kybs/{session_id}: Update client details.

Verification Details (Third Party)

• POST /verification/{client_id}/{session_id}: Store third-party verification data.

• GET /verification/{client_id}/{session_id}/{source}: Retrieve verification data.

Verification Session

• POST /verification-session/: Create a new verification session.

• GET /verification-session/: List verification sessions with filtering.

• GET /verification-session/{session_id}: Retrieve a specific session.

• PATCH /verification-session/{session_id}: Update a session.

• DELETE /verification-session/{session_id}: Delete a session.

• POST /verification-session/invite: Invite users to a session.

• GET /verification-session/verify/{session_id}: Open chat interface for verification.

• GET /verification-session/invites/: List session invites.

• GET /verification-session/verification-summary-periodic/{client_id}: Get periodic verification summary.

Flow Configuration

• GET /flow-config/{flow_id}: Retrieve a flow configuration.

• PUT /flow-config/{flow_id}: Update a flow configuration.

• DELETE /flow-config/{flow_id}: Delete a flow configuration.

• GET /flow-config: List flow configurations with pagination.

• POST /flow-config: Create a new flow configuration.

Next Steps

To dive deeper, explore the detailed endpoint documentation in the GitBook sidebar. Each section includes full schema definitions, request/response examples, and error handling details. For authentication details or to obtain an API key, contact our support team at [e-mail].

Get started today and integrate Beetlelabs' verification capabilities into your application!