Data dictionary
This is a field-level reference for the key objects the Know Your Customer Limited Public API v2 returns. It groups the fields you will read most often into identifiers, the case and status lifecycle, members and ownership, documents, AML, and IDV, with the type, where the field appears, its meaning, and a stability note for each. Read it alongside the Guide for the concepts and the API Reference for the full contract.
The Notes column is the part to read carefully: it flags which fields are stable to depend on, which are optional or nullable, which vary by jurisdiction, and which you should not hard-code against.
A case does not report readiness through its status text. The status string can stay "Open" while the numeric statusId climbs through the build. Treat a case as ready when statusId is 3 and the structure is populated (members present, or org-chart nodes present). Do not key readiness off the status text, and do not key it off statusId alone. See Status progression.
Identifiers
These are the identifiers you pass between calls to address a case, a search match, a step, or an ownership link.
| Field | Where it appears | Type | Meaning | Notes |
|---|---|---|---|---|
caseCommonId | Company case, individual case, each member | integer | The unique identifier of a case. Returned when you create a case and used on every later call about it. Each individual member also has its own caseCommonId. | Stable. The primary key you carry through a journey. Not optional on a created case. |
externalCode | Search result, create-company request | string | The registration number the registry assigns to a company. Supply it (with the country) for an exact match when creating a case. | Stable per company within a registry. Format varies by jurisdiction, so treat it as an opaque string, do not parse it. |
rawname | Search result, create-company request | string | The company name exactly as the registry returns it. You pass the rawname from a search result back into case creation. | Use the value as returned. Do not reformat or title-case it, the create call matches on the registry form. |
codeiso31662 | Search request, create-company request, member | string | The ISO 3166-2 country code identifying the jurisdiction, for example GB, SG, or HK. Routes the case to the correct registry. | Stable. Note the casing of the key varies across payloads (for example codeiso31662 on requests, codeISO31662 on some member objects), so match the key exactly as documented for each call. |
caseStepId | Steps, members, uploaded documents, org-chart node | integer | The unique identifier of a step within a case: one unit of verification work (registry fetch, document, AML, and so on). | Stable within a case. Use it to read, update, or note a specific step. |
caseLinkId | Org-chart node | integer | Identifies the ownership link (the edge) that connects a node to its parent in the org-chart, as distinct from the party itself. | Stable within a case. Distinguishes the same party appearing under more than one parent. |
Case and status lifecycle
A company case is built asynchronously. You create it, then poll it until it is ready. These fields describe the case and its progress.
| Field | Where it appears | Type | Meaning | Notes |
|---|---|---|---|---|
statusId | Case common block | integer (enum) | The numeric build status of the case. Progresses through the build to the terminal value 3 (Ready). Observed set: {0, 3, 9, 50, 51, 53, 54, 100, 107}. | Poll this, but do not treat readiness as statusId == 3 alone: combine it with a populated structure. See below. |
status | Case common block | string, nullable | A human-readable status label. | Do NOT use for readiness. The text can remain "Open" while statusId climbs. It is display text, not a control signal. |
statusName | Case common block | string, nullable | A display name for the current status. | Informational only. Same caution as status: do not key logic off it. |
caseDecision | Case common block | string, nullable | The decision recorded on the case (for example the outcome you set when you close it). | Optional, null until you record a decision. |
type / typeString | Case common block | integer (enum) / string | Whether the case is a company case or an individual case (the enum has two values). typeString is the readable form. | Stable per case. A case does not change type. |
isDeactivated | Case common block, member, step | boolean | Marks a case, member, or step that does not require full verification (for example a minority shareholder below the shareholding threshold). It has still been screened against AML and sanctions lists. | Stable. A deactivated step can be activated where full verification is required. |
scheduledReviewDate / lastReviewDate | Case common block | string (date-time), nullable | The next scheduled re-review date and the date of the last review, driving ongoing-due-diligence cadence. | Optional, null until set. |
allUbosIdentified | Company case details | string | Whether every ultimate beneficial owner was identified for the company. | A Title-case string, "Yes" or "No", not a boolean. Compare against those exact strings, do not coerce to a boolean. |
Status progression
The typical progression, and the meaning of each status:
| statusId | Stage | Meaning |
|---|---|---|
0 | Open | Initializing. The case has been created and the build has not started. |
50 | Processing | Queued for build. |
51 | Processing | Fetching the registry record. |
53, 54 | Processing | Build sub-steps. A varying subset appears depending on the case. |
9 | Processing | Google search step. |
100 | Processing | AML checks. |
107 | Processing | Building the structure. |
3 | Ready | Terminal ready state. The case is built. |
A case moves 0 then 50 then 51 then a varying subset of {53, 54, 9, 100, 107} then 3. Not every case passes through every intermediate status, and the subset differs by jurisdiction and by what the case requires. Do not assume any single intermediate value (for example 100) always appears. A case that does not complete can also end failed or expired rather than reaching 3; handle a terminal non-ready outcome as well as success.
Ready = statusId is 3 AND the structure is populated: members present (member count greater than zero) or org-chart nodes present (node count greater than zero). This structural check is the reliable readiness test. The status text is not, and statusId on its own is not.
Members and ownership
A company case resolves the parties who own and control the company. They appear both as a flat member list and as a recursive org-chart. These fields describe both.
| Field | Where it appears | Type | Meaning | Notes |
|---|---|---|---|---|
memberType | Member (case member) | string (enum) | Whether the member is an individual or a company. Values are "Individual" and "Company". | Stable string enum. Note the object schemas are named IndividualMember and CompanyMember, but the discriminator value on the wire is the memberType string. Branch on the string. |
controllingEntitiesAndIndividuals | Company members detail | array of member objects | The parties that control the company (its controlling entities and individuals). A parallel controllingEntitiesAndIndividualsTitle carries the display label. | May be empty for some structures. Iterate defensively. |
shareholdersAndBeneficialOwners | Company members detail | array of shareholder objects | The shareholders and beneficial owners of the company. | Present on a built company case. Can be empty depending on the structure. |
role | Org-chart node, shareholder, officer | string, nullable | The party’s role in the structure. Observed values include "Subject" (the company being verified) and director or shareholder roles. | Treat as an open string set, new roles can appear. Note one live value is spelled "Spose" (a spelling of “Spouse”). Match the value as returned, do not assume the corrected spelling. |
effectivePercentage | Org-chart node | number, nullable | The effective ownership percentage a node holds, after tracing through intermediate companies. | May be null when the percentage is not resolvable. Do not assume a number is always present. |
shares | Org-chart node, shareholder | number, nullable | The raw share count or holding recorded for the party. | Optional, nullable. Distinct from effectivePercentage. |
registryProcessed | Company member | string, nullable | Indicates whether the member company’s own registry record was processed. | A string, not a boolean. Read it as a string value. |
isDeactivated | Member, step | boolean | See the case and status table: a minority or already-cleared party that has been screened but does not need full verification. | Stable. Activatable where full verification is required. |
Org-chart node
The org-chart is a recursive tree. A root company node carries nested arrays of children, and each child is itself an org-chart node with the same shape, so ownership can run through many levels of holding companies down to the individuals (the UBOs) at the leaves.
| Field | Where it appears | Type | Meaning | Notes |
|---|---|---|---|---|
name | Org-chart node | string, nullable | The party’s name. | Present on resolved nodes. |
shareholders | Org-chart node | array of org-chart nodes, nullable | The node’s shareholders, each a full org-chart node. This is the recursion: a shareholder can itself be a company with its own shareholders. | Recurse to find UBOs. May be null or empty at a leaf. Walk the tree, do not read one level. |
officers, others, jointShareholderMembers | Org-chart node | array of org-chart nodes, nullable | Further child collections on a node: officers, other related parties, and joint shareholders. | All nullable. Include them when walking the tree if you need the full structure. |
caseCommonId, caseStepId, caseLinkId | Org-chart node | integer | Identifiers linking the node back to its case, its step, and its ownership link. See Identifiers. | Use caseCommonId to address an individual node as a case in its own right. |
Where a case carries risk ratings (client, channel, product, country, and total), each rating’s color is an integer enum, not a string. It is a number in the range 0 to 5. Do not compare it against a string such as "Green", map the integer to your own label.
Documents
A company case retrieves registry documents; an individual case collects identity documents. Uploaded and retrieved documents share a common shape.
| Field | Where it appears | Type | Meaning | Notes |
|---|---|---|---|---|
category | Document, upload result | string, nullable | The document’s category. Documents fall into two categories: Retrieved by default (collected as part of the case) and Available on demand (obtainable when you request them). | Use exactly these two category concepts. Do not label documents “mandatory” versus “non-mandatory”, that is not the model. |
name | Document, upload result | string, nullable | The document’s name or title. | Display text. |
link | Document, upload result | string, nullable | Where the document can be retrieved. Use it to download the stored document for that case. | Address the specific stored document via this link. |
dataSource | Document leaf, member | string (opaque code) | An opaque code identifying where a data point or document originated (for example "HKCR"). | Treat as an opaque identifier only. It is a code, not a label to display, and not something to build a lookup against beyond noting that the field exists. |
caseDocumentId | Upload result | integer | Identifies the stored document. | Stable per stored document. |
prevalidationMessages | Upload result | array of key/value pairs, nullable | Validation findings on an uploaded document. Empty for an acceptable document; carries a message such as IdentityDocumentNotRecognized for one that is not. | An empty array means no findings. Always check it, do not assume upload implies acceptance. |
AML
AML screening (sanctions, PEP, and adverse-media) runs as part of a case. The result is a summary you read on the case, with per-category outcomes.
| Field | Where it appears | Type | Meaning | Notes |
|---|---|---|---|---|
isCaseAMLPositive | Company details, shareholder, officer, UBO | boolean | Whether the party has an AML match that has not been excluded. | Stable boolean. A clear party is false. |
caseAmlSummary | Company details, member | summary object | The AML summary for a case or party. Contains a worldCheckSummary and a lexisNexisCheckSummary. | Read the summary rather than assuming a single flag captures everything. |
worldCheckSummary | AML summary | object of per-category values | Per-category screening outcomes: pep, sanctions, soe, crimes, terrorism, lawEnforcement, regulatoryEnforcement, other, and more. | Each category is one of the summary values below. Iterate the categories rather than checking one. |
| category value | Each category above | string (enum) | The outcome for a category. One of "NA", "NoMatches", "HasMatches", "AllMatchesExcluded". | "AllMatchesExcluded" means matches existed but were dismissed as false positives. Treat it distinctly from "NoMatches". |
IDV (identity verification)
Identity documents on an individual case are verified through a third-party identity-verification provider (Au10tix) under the hood. The verdict fields below appear at a high level on an individual’s identity result. They are surfaced through the API; the underlying verification is performed by the provider.
| Field | Where it appears | Type | Meaning | Notes |
|---|---|---|---|---|
triggeredRule | Individual identity result | string | The rule that determined the verdict on the submitted identity document (for example the rule that flagged it). | Provider-supplied. Treat the value as an opaque label, the rule set can change. |
forgeryTests | Individual identity result | collection | The document-forgery tests run against the identity document and their outcomes. | Read as a collection of test outcomes, not a single pass or fail. |
identityReport | Individual identity result | object | The overall identity-verification report for the individual, assembling the provider’s findings. | The high-level container for the verdict. Do not depend on a fixed internal shape; read the fields you need defensively. |
In the sandbox, identity verdicts are driven by the sample identity documents you upload, so you can exercise both an accepted document and a rejected one (which returns a prevalidation message such as IdentityDocumentNotRecognized). Sandbox results are for evaluation only and are not for production compliance use.