Every endpoint, specified

Base URL & environments

All requests are made over HTTPS to a single base URL. The environment is selected by the key you authenticate with, not by the URL: sk_test_ keys operate on isolated sandbox data and never touch a live registry, watchlist, or invoice; sk_live_ keys run real verifications and are billed.

https://api.clearbound.xyz/v1

Requests and responses are JSON. Send Content-Type: application/json on every request with a body, and authenticate with a bearer header: Authorization: Bearer sk_live_…. Plain HTTP requests are rejected at the edge before they reach your data.

Versioning

The API version is pinned in the URL path (/v1). Within a major version we only make additive changes: new endpoints, new optional parameters, and new response fields. Your integration should ignore fields it does not recognize. Breaking changes ship as a new major version with at least twelve months of overlap, announced through the dashboard and the clearbound-changes mailing list.

Every response includes an X-Clearbound-Version header with the exact build that served it, which support will ask for when debugging.

Idempotency

All POST endpoints accept an Idempotency-Key header. If a request with the same key is retried within 24 hours, the API returns the original response instead of running the operation again. This makes it safe to retry on network failure without creating (and being billed for) a duplicate verification.

curl https://api.clearbound.xyz/v1/verifications \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: 8d4f2a1c-onboard-4412" \
  -d '{ "legal_name": "Northwind Ventures LLC", "country": "US", "checks": ["registry"] }'

Use a key that identifies the operation in your own system, for example your onboarding case ID, so retries collapse naturally.

Pagination

All list endpoints are cursor-paginated and share the same three parameters:

• limit: number of objects to return, 1–100. Defaults to 25.
• starting_after: an object ID; returns the page after it.
• ending_before: an object ID; returns the page before it.

List responses wrap their results in a common envelope with has_more telling you whether another page exists:

{
  "object": "list",
  "data": [ … ],
  "has_more": true,
  "url": "/v1/verifications"
}

Verifications

A verification is one complete KYB run against one business: the checks you requested, their individual results, and the rolled-up decision and risk_score. Verifications are immutable once completed; re-running a business creates a new verification with a new ID. The full field list is described in the verification object guide.

POST /v1/verifications

Creates and runs a verification. Blocks until every requested check resolves (typically under a minute); long-running document reviews can instead be consumed asynchronously via webhooks.

• legal_name required: the registered legal name of the business.
• registration_number: the local registry or company number, if known.
• country required: ISO 3166-1 alpha-2 code; selects the registry.
• checks required: any of registry, ubo, sanctions, documents, adverse_media.
• monitoring: true to enrol the business into continuous monitoring on completion.
• external_id: your own identifier for the case, echoed back on the object and in webhooks.

GET /v1/verifications/:id

Retrieves a verification by ID. Returns the complete object including per-check results, the mapped owner tree, document findings, and the decision. IDs are prefixed vrf_ and stable for the life of the record.

GET /v1/verifications

Lists verifications in reverse-chronological order. Supports the standard pagination parameters plus:

• status: filter by pending, processing, completed, or review_required.
• decision: filter by approve, review, or decline.
• external_id: return verifications tagged with your identifier.
• created[gte] / created[lte]: Unix-timestamp range filters.

POST /v1/verifications/:id/review

Records the outcome of a human review on a verification in review_required status. The verification moves to completed with the reviewer's decision, and the reviewer identity and note are appended to the audit trail.

• decision required: approve or decline.
• note: free-text rationale, stored on the immutable record.
• reviewer: email or ID of the person who made the call.

Businesses

A business is the durable profile behind verifications: the resolved registry identity, current status, and monitoring state. Verifying a company for the first time creates its business object automatically; subsequent verifications attach to it.

GET /v1/businesses/:id

Retrieves a business by ID (prefixed biz_). The object includes the resolved registry identity, incorporation details, current registry status, the IDs of all verifications run against it, and whether it is currently monitored.

{
  "id": "biz_2fa8e91d04",
  "legal_name": "Northwind Ventures LLC",
  "registration_number": "DE-7421199",
  "country": "US",
  "registry_status": "active",
  "incorporated": 1520899200,
  "verifications": ["vrf_8c21f0a4e7"],
  "monitored": true
}

GET /v1/businesses

Lists businesses you have verified, with the standard pagination parameters plus country and registry_status filters.

Beneficial owners

The ownership graph behind a business, resolved during any verification that includes the ubo check. Ownership is walked through intermediate holding companies until it reaches natural persons or exchange-listed entities.

GET /v1/businesses/:id/owners

Returns the full owner tree for a business as a flat list of edges, each linking a parent entity to an owner with a percentage. Every natural person in the tree carries their own screening result.

• type: person, company, or listed_entity.
• ownership_pct: direct ownership on this edge, 0–100.
• effective_pct: ownership of the root business after multiplying through the chain.
• verified: whether the owner's identity was confirmed against source documents.
• screening: clear or hit across sanctions and PEP lists (persons only).

Pass threshold (default 25) to only return owners above an effective-ownership percentage, matching most regulatory UBO definitions.

Monitors

A monitor keeps a verified business under continuous watch: registry status, sanctions and PEP list updates, ownership changes, and adverse media. When something changes, the monitor emits an alert and a monitoring.alert webhook event.

POST /v1/monitors

• business required: the biz_ ID to watch.
• signals: any of registry, sanctions, ownership, adverse_media. Defaults to all.
• frequency: daily or realtime. Watchlist deltas are always applied in real time; frequency governs full registry re-checks.

GET /v1/monitors/:id

Retrieves a monitor (prefixed mon_), including its signal configuration, state (active or paused), and the timestamp of the last completed sweep.

DELETE /v1/monitors/:id

Stops monitoring. The monitor and its alert history remain readable for audit purposes; the business simply stops being watched. Deletion takes effect immediately and stops billing for that monitor at the end of the current day.

Alerts

An alert is one detected change on one monitored business: what changed, when we saw it, and the evidence. Alerts are immutable; acknowledging one records who looked at it and what they decided.

GET /v1/monitors/:id/alerts

Lists alerts for a monitor, newest first, with the standard pagination parameters plus a severity filter (info, elevated, critical).

{
  "id": "alr_91bd03fe",
  "monitor": "mon_5e77c2a9",
  "severity": "critical",
  "signal": "sanctions",
  "summary": "UBO added to EU consolidated list",
  "detected": 1782604800,
  "acknowledged": null
}

POST /v1/alerts/:id/acknowledge

Marks an alert as handled. Accepts an optional note and reviewer, both appended to the audit trail. Acknowledged alerts stop counting toward the unresolved total shown in the dashboard.

Screenings

A standalone watchlist screening of a single party — a person or an entity — without running a full verification. Useful for re-screening an individual owner or checking a counterparty ad hoc. The same engine powers the sanctions check inside verifications.

POST /v1/screenings

• type required: person or entity.
• name required: full name to screen.
• date_of_birth: ISO 8601 date; sharply reduces false positives for persons.
• country: nationality or registration country, used for list weighting.
• lists: any of ofac, eu, un, pep, adverse_media. Defaults to all.

Returns clear or hit, and on a hit, the matched list entries with match strength and source links so a reviewer can adjudicate quickly.

Documents

Supporting documents — certificates of incorporation, articles, registers of members, proofs of address — uploaded for review. Document review checks authenticity signals and extracts structured fields that are cross-checked against registry data.

POST /v1/documents

Uploads a document as multipart/form-data. Accepts PDF, PNG, and JPEG up to 25 MB.

• file required: the document itself.
• type required: e.g. certificate_of_incorporation, articles, register_of_members, proof_of_address.
• business: the biz_ ID to attach it to.

GET /v1/documents/:id

Retrieves a document's review result (prefixed doc_): authenticity (passed, flagged, or failed), the extracted fields, and any mismatches against the registry record. The original file is available for 90 days via a signed, expiring download_url.

Webhook endpoints

Register HTTPS endpoints to receive events as verifications resolve and monitored businesses change. Delivery semantics — signatures, the 5-second acknowledgement window, and 24-hour exponential-backoff retries — are covered in the webhooks guide.

POST /v1/webhook_endpoints

• url required: your HTTPS endpoint.
• events: array of event types to deliver. Defaults to all.

The response includes the endpoint's signing secret (shown once) used to verify the Clearbound-Signature header on every delivery.

GET /v1/webhook_endpoints

Lists your registered endpoints and their status. An endpoint that has failed every delivery for 5 consecutive days is moved to disabled and must be re-enabled from the dashboard.

DELETE /v1/webhook_endpoints/:id

Removes an endpoint. In-flight deliveries finish their retry schedule; no new events are queued.

Event types

• verification.completed: a verification finished and reached a decision.
• verification.review_required: a verification needs human review before you act.
• verification.reviewed: a human review was recorded via the API or dashboard.
• monitoring.alert: a monitored business changed — new sanctions hit, registry status, or ownership.
• document.reviewed: an uploaded document finished authenticity review.
• screening.hit: a standalone screening matched a watchlist entry.

Every event envelope carries id (prefixed evt_), type, created, and the affected resource under data. Events are also queryable for 30 days at GET /v1/events, which is the recommended way to backfill after downtime on your side.

The error object

Every non-2xx response carries a single error object with a stable machine-readable code, a human-readable message, and — for validation failures — the param that caused it.

# → 422 Unprocessable Entity
{
  "error": {
    "code": "invalid_country",
    "message": "country must be an ISO 3166-1 alpha-2 code",
    "param": "country",
    "doc_url": "https://clearbound.xyz/api-reference#error-object"
  }
}

Common codes: authentication_failed (401), insufficient_permissions (403), not_found (404), idempotency_conflict (409, same key with a different body), validation_failed (422), rate_limited (429, honor Retry-After), and internal_error (500, safe to retry idempotently). HTTP status semantics and limits are summarized in the documentation.