BID API Specification

1. Overview

BID (Beneficiary Identity Dispatch) is a fee-for-service API that banks and financial institutions use to verify beneficiary identity before releasing funds. BID creates a cryptographic binding between a beneficiary's identity, their account, and the settlement instruction - preventing fraud, misdirected wires, and business email compromise attacks.

• Base URL: https://jilsovereign.com/api/bid
• Protocol: HTTPS (TLS 1.3)
• Content-Type: All requests and responses are application/json
• Version: v1
• Encoding: UTF-8
• Endpoints: 12 total - 7 core binding operations + 5 identity verification checks

Every verification produces a cryptographic receipt hash that can be anchored to the JIL ledger for immutable audit trails. The trust score system provides a quantified confidence level for each identity binding.

The API is organized into two groups: Core BID Endpoints (register, verify, status, submit, history, admin, health) for identity binding and settlement dispatch, and Identity Verification Checks (phone, email, address, person, company) for standalone KYC/KYB verification that can be used independently or linked to existing BID records.

2. Authentication

All endpoints (except /health) require an API key. HMAC signing is optional but recommended for production deployments.

API Key (Required)

Include your API key in the x-api-key header with every request:

x-api-key: your_api_key_here

HMAC Signature (Optional)

For additional security, you can sign requests with HMAC-SHA256. When present, the server validates the signature before processing the request.

HMAC message format:

{METHOD}{PATH}{TIMESTAMP}{SHA256(BODY)}

Example for a POST to /v1/bid/verify:

POST/v1/bid/verify1709312400000e3b0c44298fc1c149afbf4c8996fb924...
                                   ^--- SHA-256 of the JSON body

3. Rate Limiting

Rate limits are enforced per API key. Every response includes rate limit headers so clients can self-regulate.

Limits by Plan

When the limit is exceeded, the API returns 429 Too Many Requests with a retry_after_seconds field in the response body:

{
  "ok": false,
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 12 seconds.",
  "retry_after_seconds": 12
}

4. Endpoints

4.1 Register Beneficiary Identity Binding

POST /v1/bid/register

Register a new beneficiary identity binding. Creates the cryptographic binding between the beneficiary's identity, their account, and the public key. This is a billable operation.

Request Body

{
  "instruction_id": "INS-20260301-0001",
  "beneficiary_account": "GB29NWBK60161331926819",
  "beneficiary_lei": "529900T8BM49AURSDO55",
  "beneficiary_legal_name": "Acme Trading Ltd",
  "beneficiary_country": "GB",
  "binding_signature": "base64-encoded-ed25519-signature",
  "public_key": "base64-encoded-ed25519-public-key",
  "metadata": {
    "reference": "INV-2026-4521",
    "department": "Treasury"
  }
}

Response (201 Created)

{
  "ok": true,
  "bid_id": "BID-A1B2C3D4",
  "binding_hash": "a3f2c8e1d4b5a6f7e8c9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
  "verified": true,
  "trust_score": 80,
  "compliance_decision": "clear",
  "receipt_hash": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1a2b3c4d5e6f7a8b9c0d1e2f3a4b5",
  "fee_charged": {
    "cents": 50,
    "display": "$0.50"
  }
}

4.2 Verify Existing Binding

POST /v1/bid/verify

Verify an existing identity binding. This is the main fee operation - banks call this endpoint each time they need to confirm a beneficiary's identity before releasing funds. The binding must have been previously registered via /v1/bid/register.

Request Body

{
  "binding_hash": "a3f2c8e1d4b5a6f7e8c9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
  "instruction_id": "INS-20260301-0002",
  "beneficiary_account": "GB29NWBK60161331926819",
  "beneficiary_lei": "529900T8BM49AURSDO55",
  "public_key": "base64-encoded-ed25519-public-key",
  "binding_signature": "base64-encoded-ed25519-signature"
}

Response (200 OK)

{
  "ok": true,
  "verified": true,
  "trust_score": 82,
  "compliance_decision": "clear",
  "verification_count": 3,
  "receipt_hash": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
  "fee_charged": {
    "cents": 50,
    "display": "$0.50"
  }
}

4.3 Check Binding Status

GET /v1/bid/status/:binding_hash

Free read-only lookup of a binding's current status. No fee is charged. Use this to check whether a binding is active, its trust score, and verification count before deciding whether to call verify.

Response (200 OK)

{
  "ok": true,
  "binding_hash": "a3f2c8e1d4b5a6f7e8c9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
  "status": "active",
  "trust_score": 82,
  "verification_count": 3,
  "endpoint_version": "v1",
  "last_verified_at": "2026-03-01T14:22:08.000Z",
  "created_at": "2026-02-28T09:15:33.000Z"
}

4.4 Full E2E Dispatch

POST /v1/bid/submit

Full end-to-end dispatch. JIL constructs the identity binding, verifies it, and forwards the verified BID to the receiving bank's callback URL. This is the highest-fee operation because it combines registration, verification, and delivery in a single call.

Request Body

{
  "instruction_id": "INS-20260301-0003",
  "beneficiary_account": "GB29NWBK60161331926819",
  "beneficiary_lei": "529900T8BM49AURSDO55",
  "beneficiary_legal_name": "Acme Trading Ltd",
  "beneficiary_country": "GB",
  "sending_bank_bic": "DEUTDEFF",
  "sending_bank_lei": "7LTWFZYICNSX8D621K86",
  "receiving_bank_bic": "NWBKGB2L",
  "callback_url": "https://receiving-bank.example.com/api/bid/inbound",
  "amount": "2500000.00",
  "currency": "USD",
  "reference": "INV-2026-4521"
}

Response (201 Created)

{
  "ok": true,
  "submission_id": "SUB-A1B2C3D4E5F6",
  "bid_id": "BID-A1B2C3D4",
  "binding_hash": "a3f2c8e1d4b5a6f7e8c9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
  "status": "forwarded",
  "trust_score": 80,
  "receipt_hash": "f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7",
  "fee_charged": {
    "cents": 100,
    "display": "$1.00"
  }
}

4.5 Audit History

GET /v1/bid/history

Paginated audit trail with billing summary. Returns all BID operations performed by the authenticated client.

Query Parameters

Response (200 OK)

{
  "ok": true,
  "page": 1,
  "limit": 20,
  "total": 142,
  "records": [
    {
      "action": "verify",
      "bid_id": "BID-A1B2C3D4",
      "binding_hash": "a3f2c8e1...",
      "instruction_id": "INS-20260301-0002",
      "trust_score": 82,
      "compliance_decision": "clear",
      "fee_cents": 50,
      "created_at": "2026-03-01T14:22:08.000Z"
    }
  ],
  "billing_summary": {
    "total_operations": 142,
    "total_fees_cents": 8400,
    "total_fees_display": "$84.00",
    "by_action": {
      "register": { "count": 30, "fees_cents": 1500 },
      "verify": { "count": 97, "fees_cents": 4850 },
      "submit": { "count": 15, "fees_cents": 1500 }
    },
    "period_start": "2026-03-01T00:00:00.000Z",
    "period_end": "2026-03-01T23:59:59.999Z"
  }
}

4.6 Create Bank Client (Admin)

POST /v1/bid/admin/clients

Admin-only endpoint. Requires the x-admin-token header in addition to the standard x-api-key. Creates a new bank client and returns the API key and HMAC secret. The HMAC secret is displayed once and cannot be retrieved again.

Request Body

{
  "bank_name": "Deutsche Bank AG",
  "bank_lei": "7LTWFZYICNSX8D621K86",
  "bank_bic": "DEUTDEFF",
  "contact_email": "treasury-ops@db.example.com",
  "plan": "pro",
  "rate_limit_override": null
}

Response (201 Created)

{
  "ok": true,
  "client_id": "CLT-D3E4F5A6B7",
  "bank_name": "Deutsche Bank AG",
  "plan": "pro",
  "api_key": "bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
  "hmac_secret": "hms_9f8e7d6c5b4a3928170f6e5d4c3b2a19",
  "rate_limit": 300,
  "created_at": "2026-03-01T10:00:00.000Z"
}

4.7 Health Check

GET /health

Unauthenticated health check. Returns service status and version. No API key required.

Response (200 OK)

{
  "ok": true,
  "service": "bid-api",
  "version": "1.0.0",
  "uptime_seconds": 86400,
  "timestamp": "2026-03-01T12:00:00.000Z"
}

5. Identity Verification Checks

Standalone identity verification endpoints for KYC (Know Your Customer) and KYB (Know Your Business) checks. Each check returns a structured result with a risk score, a per-operation fee, and an auditable receipt hash. These checks can be used independently or linked to an existing BID record via the optional bid_record_id field.

5.1 Phone Verification

POST /v1/bid/check/phone

Verify a phone number - format validation, line type classification, carrier lookup, reachability assessment.

Request Body

{
  "phone_number": "+14155551234",
  "country_code": "1",            // optional
  "expected_name": "John Doe",     // optional - for name match
  "bid_record_id": "bid_..."        // optional - link to existing BID record
}

Response (200 OK)

{
  "ok": true,
  "check_id": "chk_phone_abc123",
  "check_type": "phone",
  "is_valid": true,
  "phone_type": "mobile",
  "country_code": "1",
  "carrier": "T-Mobile",
  "is_reachable": true,
  "risk_score": 5,
  "formatted_number": "+14155551234",
  "fee_charged": { "cents": 10, "display": "$0.10" },
  "receipt_hash": "sha256..."
}

5.2 Email Verification

POST /v1/bid/check/email

Verify an email address - syntax validation, MX record lookup, disposable email detection, deliverability check.

Request Body

{
  "email_address": "john.doe@bankofamerica.com",
  "expected_name": "John Doe",    // optional
  "bid_record_id": "bid_..."       // optional
}

Response (200 OK)

{
  "ok": true,
  "check_id": "chk_email_abc123",
  "check_type": "email",
  "is_valid": true,
  "is_deliverable": true,
  "is_disposable": false,
  "is_free_provider": false,
  "is_role_account": false,
  "mx_found": true,
  "domain": "bankofamerica.com",
  "risk_score": 0,
  "fee_charged": { "cents": 10, "display": "$0.10" },
  "receipt_hash": "sha256..."
}

5.3 Address Verification

POST /v1/bid/check/address

Verify a physical address - format validation, postal code patterns, standardization, country-specific rules.

Request Body

{
  "street_line_1": "100 Federal Street",
  "street_line_2": "Suite 2000",       // optional
  "city": "Boston",
  "state_province": "MA",              // optional
  "postal_code": "02110",              // optional
  "country_code": "US",
  "bid_record_id": "bid_..."            // optional
}

Response (200 OK)

{
  "ok": true,
  "check_id": "chk_addr_abc123",
  "check_type": "address",
  "is_valid": true,
  "is_deliverable": true,
  "is_residential": false,
  "is_commercial": true,
  "standardized_address": "100 Federal Street, Suite 2000, Boston, MA, 02110, US",
  "match_score": 100,
  "latitude": 42.3554,
  "longitude": -71.0541,
  "fee_charged": { "cents": 10, "display": "$0.10" },
  "receipt_hash": "sha256..."
}

5.4 Person Verification

POST /v1/bid/check/person

Verify personal identity - name match against account records, sanctions screening, PEP status check, adverse media. For personal accounts: is this person on the account?

Request Body

{
  "full_name": "John Michael Doe",
  "date_of_birth": "1985-03-15",       // optional
  "account_number": "****1234",         // optional
  "bank_name": "Bank of America",       // optional
  "phone": "+14155551234",              // optional - cross-reference
  "email": "john.doe@email.com",        // optional - cross-reference
  "address": "100 Federal Street, Boston, MA 02110",  // optional
  "country": "US",                      // optional
  "bid_record_id": "bid_..."              // optional
}

Response (200 OK)

{
  "ok": true,
  "check_id": "chk_person_abc123",
  "check_type": "person",
  "identity_verified": true,
  "name_match_score": 85,
  "address_match_score": 80,
  "sanctions_clear": true,
  "pep_status": false,
  "adverse_media": false,
  "risk_level": "low",
  "fee_charged": { "cents": 75, "display": "$0.75" },
  "receipt_hash": "sha256..."
}

5.5 Company Verification

POST /v1/bid/check/company

Verify a company or business entity - registration status, good standing, jurisdiction, LEI validation, officer identification, sanctions screening. For company accounts: is this entity registered and in good standing?

Request Body

{
  "company_name": "Acme Financial Corp",
  "registration_number": "12-3456789",    // optional - EIN/Companies House number
  "lei": "5493001KJTIIGC8Y1R17",          // optional - Legal Entity Identifier
  "jurisdiction": "Delaware",              // optional
  "country": "US",
  "bid_record_id": "bid_..."               // optional
}

Response (200 OK)

{
  "ok": true,
  "check_id": "chk_company_abc123",
  "check_type": "company",
  "is_registered": true,
  "registration_status": "active",
  "is_good_standing": true,
  "registration_date": "2015-06-20",
  "registered_address": "1209 Orange Street, Wilmington, DE 19801",
  "officers": [
    { "name": "Jane Smith", "role": "CEO" },
    { "name": "Robert Chen", "role": "CFO" }
  ],
  "ubo_identified": true,
  "sanctions_clear": true,
  "risk_level": "low",
  "fee_charged": { "cents": 800, "display": "$8.00" },
  "receipt_hash": "sha256..."
}

6. Webhook Callback Specification

When a bank calls /v1/bid/submit, JIL constructs and verifies the identity binding, then forwards the verified BID to the receiving bank's callback_url via an HTTP POST.

Webhook Payload

{
  "submission_id": "SUB-A1B2C3D4E5F6",
  "bid_id": "BID-A1B2C3D4",
  "binding_hash": "a3f2c8e1d4b5a6f7e8c9d0a1b2c3d4e5...",
  "instruction_id": "INS-20260301-0003",
  "beneficiary_account": "GB29NWBK60161331926819",
  "beneficiary_legal_name": "Acme Trading Ltd",
  "beneficiary_country": "GB",
  "beneficiary_lei": "529900T8BM49AURSDO55",
  "sending_bank_bic": "DEUTDEFF",
  "sending_bank_lei": "7LTWFZYICNSX8D621K86",
  "trust_score": 80,
  "compliance_decision": "clear",
  "verified": true,
  "verified_at": "2026-03-01T14:30:00.000Z",
  "receipt_hash": "f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1...",
  "amount": "2500000.00",
  "currency": "USD",
  "reference": "INV-2026-4521"
}

Webhook Headers

Expected Behavior

• The receiving bank must respond with a 2xx status code within 15 seconds
• If the callback times out or returns a non-2xx code, the submission status is set to forward_failed
• Retry policy: Single attempt only - no automatic retry. The sending bank can check submission status and re-trigger via a new /v1/bid/submit call if needed
• The receiving bank should validate the X-BID-Source header and the receipt_hash for authenticity

7. Error Codes

All error responses follow a consistent structure:

{
  "ok": false,
  "error": "error_code",
  "message": "Human-readable description of the error."
}

8. Trust Score

Every BID operation produces a trust score between 0 and 100. The score quantifies confidence in the identity binding and is composed of four weighted factors:

Score Interpretation

9. Fee Schedule

Fees are charged per operation. Monthly plan pricing includes the base platform fee plus per-operation charges. All fees are in USD.

10. Code Examples

# Register a beneficiary identity binding
curl -X POST https://jilsovereign.com/api/bid/v1/bid/register \
  -H "Content-Type: application/json" \
  -H "x-api-key: bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6" \
  -d '{
    "instruction_id": "INS-20260301-0001",
    "beneficiary_account": "GB29NWBK60161331926819",
    "beneficiary_lei": "529900T8BM49AURSDO55",
    "beneficiary_legal_name": "Acme Trading Ltd",
    "beneficiary_country": "GB",
    "binding_signature": "dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVk...",
    "public_key": "MCowBQYDK2VwAyEA..."
  }'

# Verify an existing binding
curl -X POST https://jilsovereign.com/api/bid/v1/bid/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6" \
  -d '{
    "binding_hash": "a3f2c8e1d4b5a6f7...",
    "instruction_id": "INS-20260301-0002",
    "beneficiary_account": "GB29NWBK60161331926819",
    "public_key": "MCowBQYDK2VwAyEA...",
    "binding_signature": "dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVk..."
  }'

# Check binding status (free, no fee)
curl https://jilsovereign.com/api/bid/v1/bid/status/a3f2c8e1d4b5a6f7... \
  -H "x-api-key: bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6"

// Register a beneficiary identity binding
const API_KEY = "bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6";
const BASE    = "https://jilsovereign.com/api/bid";

async function registerBeneficiary() {
  const body = {
    instruction_id: "INS-20260301-0001",
    beneficiary_account: "GB29NWBK60161331926819",
    beneficiary_lei: "529900T8BM49AURSDO55",
    beneficiary_legal_name: "Acme Trading Ltd",
    beneficiary_country: "GB",
    binding_signature: "dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVk...",
    public_key: "MCowBQYDK2VwAyEA...",
  };

  const res = await fetch(`${BASE}/v1/bid/register`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY,
    },
    body: JSON.stringify(body),
  });

  const data = await res.json();
  console.log("BID ID:", data.bid_id);
  console.log("Binding hash:", data.binding_hash);
  console.log("Trust score:", data.trust_score);
  console.log("Fee:", data.fee_charged.display);
  return data;
}

async function verifyBinding(bindingHash) {
  const body = {
    binding_hash: bindingHash,
    instruction_id: "INS-20260301-0002",
    beneficiary_account: "GB29NWBK60161331926819",
    public_key: "MCowBQYDK2VwAyEA...",
    binding_signature: "dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVk...",
  };

  const res = await fetch(`${BASE}/v1/bid/verify`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY,
    },
    body: JSON.stringify(body),
  });

  return res.json();
}

// Usage
const registration = await registerBeneficiary();
const verification = await verifyBinding(registration.binding_hash);

# pip install requests
import requests
import hashlib
import hmac
import time

API_KEY  = "bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6"
HMAC_KEY = "hms_9f8e7d6c5b4a3928170f6e5d4c3b2a19"
BASE     = "https://jilsovereign.com/api/bid"

def make_headers(method, path, body_bytes=b""):
    """Build headers with optional HMAC signature."""
    ts = str(int(time.time() * 1000))
    body_hash = hashlib.sha256(body_bytes).hexdigest()
    message = f"{method}{path}{ts}{body_hash}"
    sig = hmac.new(
        HMAC_KEY.encode(), message.encode(), hashlib.sha256
    ).hexdigest()
    return {
        "Content-Type": "application/json",
        "x-api-key": API_KEY,
        "x-timestamp": ts,
        "x-signature": sig,
    }

# Register
payload = {
    "instruction_id": "INS-20260301-0001",
    "beneficiary_account": "GB29NWBK60161331926819",
    "beneficiary_lei": "529900T8BM49AURSDO55",
    "beneficiary_legal_name": "Acme Trading Ltd",
    "beneficiary_country": "GB",
    "binding_signature": "dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVk...",
    "public_key": "MCowBQYDK2VwAyEA...",
}

import json
body_bytes = json.dumps(payload).encode()
headers = make_headers("POST", "/v1/bid/register", body_bytes)

resp = requests.post(f"{BASE}/v1/bid/register", json=payload, headers=headers)
data = resp.json()
print(f"BID ID: {data['bid_id']}")
print(f"Trust score: {data['trust_score']}")
print(f"Fee: {data['fee_charged']['display']}")

# Verify
verify_payload = {
    "binding_hash": data["binding_hash"],
    "instruction_id": "INS-20260301-0002",
    "beneficiary_account": "GB29NWBK60161331926819",
    "public_key": "MCowBQYDK2VwAyEA...",
    "binding_signature": "dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVk...",
}

body_bytes = json.dumps(verify_payload).encode()
headers = make_headers("POST", "/v1/bid/verify", body_bytes)

resp = requests.post(f"{BASE}/v1/bid/verify", json=verify_payload, headers=headers)
print(resp.json())

Company Verification Check Examples

The following examples demonstrate the /v1/bid/check/company endpoint for KYB (Know Your Business) verification.

# Verify a company entity (KYB check)
curl -X POST https://jilsovereign.com/api/bid/v1/bid/check/company \
  -H "Content-Type: application/json" \
  -H "x-api-key: bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6" \
  -d '{
    "company_name": "Acme Financial Corp",
    "registration_number": "12-3456789",
    "lei": "5493001KJTIIGC8Y1R17",
    "jurisdiction": "Delaware",
    "country": "US"
  }'

# Link a company check to an existing BID record
curl -X POST https://jilsovereign.com/api/bid/v1/bid/check/company \
  -H "Content-Type: application/json" \
  -H "x-api-key: bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6" \
  -d '{
    "company_name": "Acme Financial Corp",
    "registration_number": "12-3456789",
    "country": "US",
    "bid_record_id": "BID-A1B2C3D4"
  }'

// Company verification (KYB check)
const API_KEY = "bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6";
const BASE    = "https://jilsovereign.com/api/bid";

async function verifyCompany(companyData) {
  const res = await fetch(`${BASE}/v1/bid/check/company`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY,
    },
    body: JSON.stringify(companyData),
  });

  const data = await res.json();

  if (!data.ok) {
    throw new Error(`Company check failed: ${data.message}`);
  }

  console.log("Check ID:", data.check_id);
  console.log("Registered:", data.is_registered);
  console.log("Good standing:", data.is_good_standing);
  console.log("Officers:", data.officers);
  console.log("Sanctions clear:", data.sanctions_clear);
  console.log("Risk level:", data.risk_level);
  console.log("Fee:", data.fee_charged.display);
  return data;
}

// Usage
const result = await verifyCompany({
  company_name: "Acme Financial Corp",
  registration_number: "12-3456789",
  lei: "5493001KJTIIGC8Y1R17",
  jurisdiction: "Delaware",
  country: "US",
});

// Link to an existing BID record
const linkedResult = await verifyCompany({
  company_name: "Acme Financial Corp",
  registration_number: "12-3456789",
  country: "US",
  bid_record_id: "BID-A1B2C3D4",
});

# Company verification (KYB check)
import requests
import json

API_KEY = "bid_live_k1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6"
BASE    = "https://jilsovereign.com/api/bid"

def verify_company(company_data):
    """Run a KYB company verification check."""
    headers = {
        "Content-Type": "application/json",
        "x-api-key": API_KEY,
    }

    resp = requests.post(
        f"{BASE}/v1/bid/check/company",
        json=company_data,
        headers=headers,
    )
    resp.raise_for_status()
    return resp.json()

# Basic company check
result = verify_company({
    "company_name": "Acme Financial Corp",
    "registration_number": "12-3456789",
    "lei": "5493001KJTIIGC8Y1R17",
    "jurisdiction": "Delaware",
    "country": "US",
})

print(f"Check ID: {result['check_id']}")
print(f"Registered: {result['is_registered']}")
print(f"Good standing: {result['is_good_standing']}")
print(f"Registration date: {result['registration_date']}")
print(f"Officers: {len(result['officers'])} found")
for officer in result["officers"]:
    print(f"  - {officer['name']} ({officer['role']})")
print(f"UBO identified: {result['ubo_identified']}")
print(f"Sanctions clear: {result['sanctions_clear']}")
print(f"Risk level: {result['risk_level']}")
print(f"Fee: {result['fee_charged']['display']}")

# Link to existing BID record
linked = verify_company({
    "company_name": "Acme Financial Corp",
    "registration_number": "12-3456789",
    "country": "US",
    "bid_record_id": "BID-A1B2C3D4",
})
print(f"Linked check: {linked['check_id']}")

11. Kafka Events

All BID operations emit events to the Kafka topic jil.bid.events. Events follow a consistent envelope format and can be consumed for analytics, audit logging, alerting, or downstream processing.

Event Envelope

{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "BID_VERIFIED",
  "timestamp": "2026-03-01T14:22:08.000Z",
  "source": "bid-api-v1",
  "client_id": "CLT-D3E4F5A6B7",
  "payload": { ... }
}

Event Types

12. Provider Integration Architecture

BID identity checks are powered by a multi-provider architecture that aggregates results from specialized verification vendors. Each check type routes through one or more external providers, with JIL's internal heuristic engine providing baseline validation and graceful degradation when upstream providers are unavailable.

12.1 Provider Map

12.2 Compliance & Analytics Bridge

Person and company checks route through JIL's compliance infrastructure for sanctions and risk screening. This provides a unified compliance decision across all identity verification operations.

12.3 External Vendor Summary

12.4 Graceful Degradation

BID is designed with a fail-safe architecture. When an upstream provider is unavailable, the check completes using JIL's internal heuristic engine with reduced confidence. Response fields populated by the unavailable provider return null to indicate data is pending upstream enrichment.