API Documentation

Integrate KYB verification directly into your systems

Overview

Quickkyb provides a RESTful API for programmatic access to our KYB verification platform. Integrate business verification, UBO analysis, and compliance checks directly into your existing workflows.

Getting Started

Authentication

All API requests require authentication using an API key:

Authorization: Bearer YOUR_API_KEY

Obtain your API key from the Developer Dashboard.

Base URL

https://api.quickkyb.com/v1

Rate Limits

  • Standard: 100 requests per minute
  • Enterprise: Custom limits available

Core Endpoints

1. Verify Entity

Verify a company and retrieve basic information.

POST /entities/verify

Request Body:

{
  "identifier": "12345678",
  "identifier_type": "hk_crn",
  "document_scope": "standard"
}

Response:

{
  "entity_id": "ent_1234567890",
  "status": "verified",
  "company_name": "Example Limited",
  "registration_number": "12345678",
  "incorporation_date": "2010-01-15",
  "status": "Active",
  "registered_office": "123 Main Street, Hong Kong",
  "estimated_cost": 250,
  "currency": "HKD"
}

2. Create Entity Search

Initiate a full KYB investigation with document retrieval.

POST /entities/search

Request Body:

{
  "identifier": "12345678",
  "identifier_type": "hk_crn",
  "documents": ["NAR1", "NNC1", "COI", "AOA", "BR_CERT"],
  "optional_services": ["tcsp_search", "mso_check"],
  "webhook_url": "https://your-site.com/webhook"
}

Response:

{
  "search_id": "search_abc123",
  "status": "payment_required",
  "amount": 250,
  "currency": "HKD",
  "payment_link": "https://pay.quickkyb.com/xyz789"
}

3. Get Search Status

Check the progress of an entity search.

GET /entities/search/{search_id}

Response:

{
  "search_id": "search_abc123",
  "status": "processing",
  "progress": 60,
  "current_step": "extracting_documents",
  "estimated_completion": "2025-01-21T14:30:00Z"
}

4. Get Entity Data

Retrieve complete entity information including UBOs.

GET /entities/{entity_id}

Response:

{
  "entity_id": "ent_1234567890",
  "company_name": "Example Limited",
  "registration_number": "12345678",
  "incorporation_date": "2010-01-15",
  "status": "Active",
  "registered_office": "123 Main Street, Hong Kong",
  "shareholders": [
    {
      "name": "John Doe",
      "type": "individual",
      "ownership_percentage": 35.5,
      "is_ubo": true
    },
    {
      "name": "Another Company Limited",
      "type": "corporate",
      "ownership_percentage": 64.5,
      "is_ubo": false,
      "requires_investigation": true
    }
  ],
  "directors": [
    {
      "name": "Jane Smith",
      "appointment_date": "2015-03-20"
    }
  ],
  "ubos": [
    {
      "name": "John Doe",
      "direct_ownership": 35.5,
      "indirect_ownership": 0,
      "total_ownership": 35.5
    }
  ]
}

5. Get Compliance Report

Download the full compliance report.

GET /reports/{report_id}

Query Parameters:

  • format: pdf, json, or xlsx

6. Screen Individual (KYC)

Run KYC verification on an individual.

POST /kyc/screen

Request Body:

{
  "name": "John Doe",
  "date_of_birth": "1980-05-15",
  "id_number": "A123456(7)",
  "id_type": "hk_id_card"
}

Response:

{
  "screening_id": "screen_xyz789",
  "status": "completed",
  "risk_level": "low",
  "watchlist_matches": [],
  "pep_status": false,
  "adverse_media": 0
}

Webhooks

Webhook Events

Subscribe to real-time updates for your searches:

search.completed

Fired when an entity search is completed:

{
  "event": "search.completed",
  "search_id": "search_abc123",
  "entity_id": "ent_1234567890",
  "timestamp": "2025-01-21T14:30:00Z",
  "data": {
    "status": "completed",
    "report_url": "https://api.quickkyb.com/reports/rpt_123"
  }
}

search.failed

Fired when a search fails:

{
  "event": "search.failed",
  "search_id": "search_abc123",
  "timestamp": "2025-01-21T14:30:00Z",
  "error": {
    "code": "document_unavailable",
    "message": "Document NAR1 is currently unavailable"
  }
}

payment.succeeded

Fired when payment is successful:

{
  "event": "payment.succeeded",
  "search_id": "search_abc123",
  "amount": 250,
  "currency": "HKD",
  "timestamp": "2025-01-21T14:25:00Z"
}

Setting Up Webhooks

Configure your webhook URL in the dashboard or via API:

POST /webhooks
{
  "url": "https://your-site.com/webhook",
  "events": ["search.completed", "search.failed"],
  "secret": "your_webhook_secret"
}

Error Handling

Error Response Format

{
  "error": {
    "code": "invalid_identifier",
    "message": "Invalid Hong Kong company registration number",
    "details": {
      "field": "identifier",
      "value": "ABC123"
    }
  }
}

Common Error Codes

  • invalid_identifier - Invalid company identifier
  • entity_not_found - Company not found in registry
  • payment_required - Payment needed to proceed
  • insufficient_credits - Not enough account credits
  • rate_limit_exceeded - Too many requests
  • unauthorized - Invalid API key
  • document_unavailable - Requested document unavailable

Testing

Sandbox Environment

Test your integration without incurring costs:

https://api-sandbox.quickkyb.com/v1
  • No real payments required
  • Mock data responses
  • Faster response times
  • Unlimited test requests

Pricing

  • API Access: Included with all paid searches
  • No Additional API Fees: Pay only for searches
  • Volume Discounts: Available for 100+ searches/month
  • Enterprise Plans: Custom SLA and support

Support

Need help integrating?

Get Your API Key

Ready to start building? Create an account and get your API key from the dashboard instantly.