Build KYB into your product in an afternoon

Introduction

The clearbound API runs the full Know Your Business (KYB) workflow from a single endpoint. Send a business and the checks you want, and we resolve it against government registries, map its beneficial owners (UBO), screen every party against global sanctions and PEP watchlists, review supporting documents, and roll everything up into one auditable decision with a calibrated risk score. You can also enrol any verified business into continuous monitoring so you hear about it the moment something changes.

The API is organized around predictable, resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP status codes and verbs. All requests are made to:

https://api.clearbound.xyz/v1

Every endpoint is served over HTTPS only. Plain HTTP requests are rejected before they reach your data.

Authentication

Authenticate every request with your secret API key in a bearer Authorization header. Keys come in two flavors: a sk_test_ key that hits sandbox data and never touches a live registry or watchlist, and a sk_live_ key that runs real verifications and is billed. Sandbox and live data are fully isolated. A verification created in one environment is never visible in the other.

curl https://api.clearbound.xyz/v1/verifications \
  -H "Authorization: Bearer sk_live_8c21f0a4e7" \
  -H "Content-Type: application/json"

Quickstart

Create a verification by posting a business and the checks you want to run. The call returns a complete verification object once every check resolves, typically in well under a minute.

curl https://api.clearbound.xyz/v1/verifications \
  -H "Authorization: Bearer $KEY" \
  -d '{
    "legal_name": "Northwind Ventures LLC",
    "registration_number": "DE-7421199",
    "country": "US",
    "checks": ["registry","ubo","sanctions","documents"]
  }'

# → 200 OK
{
  "id": "vrf_8c21f0a4e7",
  "status": "completed",
  "decision": "approve",
  "risk_score": 14,
  "registry": "match",
  "ubo": { "mapped": 3, "verified": 3 },
  "sanctions": "clear",
  "created": 1782518400
}

That single decision (approve, review, or decline) is calibrated to your policy thresholds, so you can act on it directly in code or route borderline cases to a reviewer with all the evidence already attached.

Create a verification

Send a POST to /v1/verifications. The body identifies the business and lists which checks to run; each value in checks maps to one of our products.

• legal_name: the registered legal name of the business (required).
• registration_number: the local registry or company number, if you have it.
• country: ISO 3166-1 alpha-2 country code that selects the right registry.
• checks: any of registry, ubo, sanctions, documents, adverse_media.
• monitoring: set true to enrol the business into continuous monitoring after the run.

The request blocks until every requested check resolves and returns the full verification object. Long-running document reviews can also be consumed asynchronously through webhooks.

The verification object

Every verification rolls its checks into one immutable, exportable record. The key fields:

• id: unique identifier, prefixed vrf_, stable for the life of the record.
• status: pending, processing, completed, or review_required.
• decision: the policy outcome: approve, review, or decline.
• risk_score: a calibrated 0–100 score; lower is safer, tuned to your thresholds.
• registry: registry match result: match, partial, or no_match, plus status and identifiers.
• ubo: ownership summary object with mapped and verified counts and the full owner tree.
• sanctions: screening result across OFAC, EU, UN, and PEP lists: clear or hit.
• documents: array of reviewed documents with type, authenticity, and extracted fields.
• created: Unix timestamp (seconds) for when the verification was created.

Webhooks

Register an HTTPS endpoint to receive events as verifications resolve and monitored businesses change. Every delivery is signed with your webhook secret so you can verify it came from us.

• verification.completed: a verification finished and reached a decision.
• verification.review_required: a verification needs human review before you act.
• monitoring.alert: a monitored business changed (new sanctions hit, registry status, or ownership).

{
  "id": "evt_4f9b2c",
  "type": "verification.completed",
  "created": 1782518431,
  "data": {
    "id": "vrf_8c21f0a4e7",
    "decision": "approve",
    "risk_score": 14
  }
}

Respond with a 2xx status within 5 seconds to acknowledge a delivery. We retry failed deliveries with exponential backoff for up to 24 hours.

SDKs

Official, typed clients wrap authentication, retries, and webhook signature verification so you can stay in your language of choice.

• Python: pip install clearbound
• TypeScript / Node: npm install clearbound
• Go: go get github.com/clearbound/clearbound-go
• Ruby: gem install clearbound

Errors

We use conventional HTTP status codes. 2xx means success, 4xx means the request was rejected (and the JSON body explains why in error.message), and 5xx means something failed on our side.

• 200: the request succeeded.
• 400: the request was malformed or missing a required field.
• 401: the API key is missing, invalid, or revoked.
• 404: the requested resource does not exist in this environment.
• 422: the body was valid JSON but failed validation.
• 500: an unexpected error on our end; safe to retry.

Rate limits

Live keys allow 100 requests per second by default, with sandbox keys held a little lower. When you exceed your limit the API returns 429 Too Many Requests along with a Retry-After header. Back off, honor the header, and retry idempotently. Need a higher limit for a bulk backfill? Talk to us and we will lift it.