Integration patterns

There is more than one way to build on the Know Your Customer Limited Public API v2, which verifies companies against live official registries across 147 jurisdictions. The right shape depends on what you need: a full corporate onboarding journey, registry data on a company you already know, a scheduled re-review, continuous monitoring after onboarding, or some combination. This page describes the main implementation styles, each with a sequence diagram you can map onto your own system.

All five styles use the same building blocks from the Guide: OAuth2 client-credentials auth, the case as the unit of work, asynchronous build that you follow either by polling or, preferably, with webhooks, and the report at the end. If you have not read the core concepts yet, start there. For the exact endpoints behind each pattern, see the API Reference, and for the field-level detail of what they return, the Data Dictionary. To try any of these against real data, request free sandbox access and see the sandbox test cases you can run.

Pattern A: Full corporate onboarding journey

This is the flagship pattern: you onboard a new corporate customer end to end. You search for the company, confirm the applicant, resolve the ownership structure and org-chart, run KYC on the directors and UBOs, review AML, record a decision, and produce the report. It is the pattern the sample onboarding app and the Verify a company, end to end walkthrough implement.

The shape of the journey:

1. Company search: find the entity in its home registry with rawname and codeiso31662.
2. Applicant confirmation: pick the correct match and create the case.
3. UBO and org-chart: read the members and the recursive ownership tree once the case is ready.
4. Director and UBO KYC: for each individual you need to verify, address their individual case and collect documents (see the UBO KYC and IDV sub-flow).
5. AML review: read AML results on the case, review and exclude false positives.
6. Decision: record the outcome on the case status.
7. Report: obtain the audit-ready PDF.

UBO KYC and identity verification (IDV)

Inside the onboarding journey, each director or UBO you verify is an individual case. You address the individual, read their documents, upload what you collect, and read back prevalidation and, for identity documents, the IDV verdict. Documents fall into two categories: Retrieved by default (already obtained for you) and Available on demand (you request or upload them). Prevalidation is synchronous and inspects the file (good, forged, or expired). Identity verification is separate: when you upload a photoid, a Government Photo ID step is verified asynchronously by a third party (Au10tix) and flips to PASSED or FAILED after roughly 15 to 30 seconds. See Documents and Beneficial ownership and individuals.

Pattern B: Registry data enrichment only

Sometimes you already know which company you are dealing with and you only need authoritative registry data: name, registration number, status, addresses, officers, and the underlying registry documents. You do not need the applicant journey, individual KYC, or a decision workflow. This is the lightest pattern.

1. Search the company by rawname and codeiso31662 (or supply the registration number in externalCode for an exact match).
2. Create the case.
3. Poll until the structure is populated, then read the entity data.
4. Retrieve the registry documents you need, then stop. You do not have to work individuals, AML review, or a decision.

The first half of the onboarding sequence above (token, search, create, poll, read) is exactly this pattern. You simply stop after reading the entity data and documents.

Pattern C: Periodic review and refresh

An existing customer needs re-verification on a schedule. You re-run the registry pull against the current register, compare what changed since last time (status, officers, ownership), update the review date, and produce a fresh report for the file.

1. Re-run the registry pull for the customer at review time (a fresh case reflects the current register).
2. Compare the new structure and status against your stored record, and flag material changes: a new director, a change in ownership, a status change.
3. Recompute AML if needed and clear any new hits.
4. Update the review date to schedule the next cycle.
5. Produce a new report as the point-in-time record.

See Review dates and Review, exclude, recompute. For always-on re-screening between reviews, use Pattern D.

Pattern D: Ongoing monitoring

After a customer is onboarded, you keep watching. You enable live monitoring on the case, consume alerts as new sanctions, PEP, or adverse-media matches appear, action each alert with a recorded decision, and keep the audit trail intact. This is perpetual KYB in practice. You can poll for alerts on a schedule, or register a webhook for the AmlMatch event so new matches are pushed to your systems as they happen instead of on your next poll.

See Live-monitoring alerts and Perpetual KYB.

Pattern E: Embedded versus backend-only

The four patterns above describe the API calls. This one is about where the calls live and what your users see. You have four options, and you can mix them.

A common shape: a bespoke customer-facing onboarding flow (embedded) backed by your server calling the API, with your compliance team using the Workspace console for review and the sample app as the reference you started from.

Clients without spare front-end or backend capacity often have Know Your Customer Limited’s own delivery team build this layer for them, at a fixed price, on the same API described here.

Async polling and latency

Every pattern that builds a case is asynchronous. You create the case, then poll until it is ready. Two rules from the case lifecycle matter for all of them:

• Readiness is the structure being populated (members present or org-chart nodes present), not a status text value and not any single intermediate statusId. The status text can stay “Open” while the case builds.
• The intermediate status set varies by case and jurisdiction. Key your logic off the terminal state, not off seeing a particular intermediate code.

For the full status table and error model, see the Reference appendix and Poll until ready.

If you would rather not poll, register a webhook for the CaseReady event and the API pushes a message the moment a case finishes building. Polling suits short-lived scripts; webhooks suit running at scale or driving work from events. See Webhooks.

Choosing a pattern

Most integrations combine several: onboard with Pattern A, keep customers under Pattern D, and re-review with Pattern C. To try any of them, request free sandbox access, read the Guide, run the sandbox test cases, and browse your cases in the Workspace console.