> For the complete documentation index, see [llms.txt](https://docs.voveid.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voveid.com/docs/kyb-know-your-business/kyb-case-management.md). # KYB Case Details ### Retrieve the Public KYB Case Details Contract This endpoint returns the customer-facing KYB case details payload for a single case. It is the public contract for retrieving structured KYB case details. ## Endpoint * **Method**: `GET` * **URL**: `/kyb/case/{refId}/details` * **Authentication**: Required (`x-api-key` header) ## When to Use This Endpoint Use this endpoint to retrieve structured KYB case details for a business using its `refId`. ## Request ### Headers ```http x-api-key: YOUR_API_KEY ``` ### Path Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------- | | `refId` | string | Yes | Your reference ID for the KYB case | ### Example Request ```bash curl -X GET https://api.voveid.com/kyb/case/unique-business-ref-12345/details \ -H "x-api-key: YOUR_API_KEY" ``` ## Response ### Success Response ```json { "id": "664b1f...", "refId": "CUST-REF-1", "status": "IN_REVIEW", "flagType": "NONE", "businessName": "Acme Inc", "flow": { "id": "flow-1", "title": "US KYB", "country": "US" }, "steps": [ { "id": "form-business_information", "type": "form", "title": "Business information", "fields": [ { "key": "business_name", "title": "Business name", "value": "Acme Inc", "type": "string", "required": true }, { "key": "registration_number", "title": "Registration number", "value": "RC-99", "type": "string", "required": false } ], "enrichment": { "names": { "legalName": "ACME INCORPORATED" }, "company": { "legalForm": "LLC", "yearStarted": 2010 } } }, { "id": "form-business_address", "type": "address", "title": "Business address", "fields": [ { "key": "street", "title": "Street", "value": "Main St", "type": "string", "required": false, "groupKey": "primary_address", "groupTitle": "Primary" }, { "key": "city", "title": "City", "value": "NYC", "type": "string", "required": false, "groupKey": "primary_address", "groupTitle": "Primary" } ] }, { "id": "documents-business_documents", "type": "document", "title": "Business documents", "documents": [ { "key": "certificate", "title": "Certificate", "required": false, "file": { "id": "uuid-cert", "originalName": "certificate.pdf", "mimeType": "application/pdf", "size": 2048, "createdAt": "2026-01-02T00:00:00.000Z", "analysis": { "matches": false }, "url": "/kyb/case/CUST-REF-1/details/documents/uuid-cert" } } ], "additionalFiles": [ { "title": "Proof", "file": { "id": "uuid-extra", "originalName": "extra.png", "mimeType": "image/png", "size": 512, "createdAt": "2026-01-03T00:00:00.000Z", "url": "/kyb/case/CUST-REF-1/details/documents/uuid-extra" } } ] }, { "id": "ubos-ubos_information", "type": "ubo", "title": "Beneficial owners", "ubos": [ { "refId": "ubo-1", "status": "completed", "fields": [ { "key": "full_name", "title": "Full name", "value": "Jane Doe", "type": "string", "required": false }, { "key": "email", "title": "Email", "value": "jane@acme.test", "type": "string", "required": false, "format": "email" } ] } ] }, { "id": "form-related_businesses", "type": "relatedBusinesses", "title": "Related businesses", "relatedBusinesses": [ { "refId": "rb-1", "fields": [ { "key": "business_name", "title": "Business name", "value": "Acme Sub LLC", "type": "string", "required": false } ], "enrichment": { "names": { "legalName": "ACME SUB LLC" } } } ] } ], "amlScreening": { "primary": [ { "refId": "CUST-REF-1", "name": "Acme Inc", "status": "NO_MATCH", "businessRole": "primary", "businessName": "Acme Inc", "caseType": "Entity", "sourceType": "KYB", "ongoingMonitoring": true, "totalHits": 0, "createdAt": "2026-01-02T00:00:00.000Z" } ], "related": [ { "refId": "rb-1", "name": "Acme Sub LLC", "status": "IN_REVIEW", "businessRole": "related", "businessName": "Acme Sub LLC", "caseType": "Entity", "sourceType": "KYB", "ongoingMonitoring": false, "totalHits": 3 } ] }, "websiteAnalysis": { "domain": "acme.test", "status": "SUCCESS", "initiatedAt": "2026-01-04T00:00:00.000Z", "completedAt": "2026-01-04T01:00:00.000Z", "data": { "score": 88 } }, "reopenHistory": [ { "stepIds": [ "form-business_information" ], "reason": "Need clearer docs", "reopenedAt": "2026-01-05T00:00:00.000Z" } ], "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-06T00:00:00.000Z" } ``` ## Response Fields ### Top-Level Fields | Field | Type | Description | | ----------------- | ------------------------ | ---------------------------------------------------------------------------------- | | `id` | string | KYB case ID | | `refId` | string | Your reference ID for the case | | `status` | string | Case status: `NOT_STARTED`, `IN_PROGRESS`, `IN_REVIEW`, `COMPLETED`, or `REJECTED` | | `flagType` | string, optional | Risk flag level such as `NONE`, `LOW`, `MEDIUM`, or `HIGH` | | `businessName` | string or null, optional | Primary business name | | `flow` | object | Flow context for the case | | `steps` | array | Ordered case steps and collected data | | `amlScreening` | object | AML screening summaries for the primary and related businesses | | `websiteAnalysis` | object, optional | Website analysis summary if available | | `reopenHistory` | array | Reopen events for the case | | `createdAt` | string, optional | Case creation timestamp in ISO 8601 format | | `updatedAt` | string, optional | Last update timestamp in ISO 8601 format | ### `flow` | Field | Type | Description | | -------------- | ---------------- | ------------------------------------- | | `flow.id` | string | Flow ID | | `flow.title` | string, optional | Flow title | | `flow.country` | string, optional | Country code associated with the flow | ### `steps` Each entry in `steps` has: | Field | Type | Description | | ------- | ------ | ----------------------------------------------------------------------- | | `id` | string | Step ID | | `type` | string | Step type: `form`, `address`, `document`, `ubo`, or `relatedBusinesses` | | `title` | string | Human-readable step title | Depending on `type`, additional keys are populated: | Step Type | Additional Fields | | ------------------- | ------------------------------------ | | `form` | `fields`, and sometimes `enrichment` | | `address` | `fields` | | `document` | `documents`, `additionalFiles` | | `ubo` | `ubos` | | `relatedBusinesses` | `relatedBusinesses` | ### `fields` A field object has: | Field | Type | Description | | ------------ | ------------------------------------ | --------------------------------------------- | | `key` | string | Schema key for the field | | `title` | string | Display label | | `value` | any | Submitted value | | `type` | string or array of strings, optional | Field type metadata | | `required` | boolean | Whether the field is required in the flow | | `format` | string, optional | Additional format information such as `email` | | `groupKey` | string, optional | Group identifier for nested field groups | | `groupTitle` | string, optional | Group title for nested field groups | ### `enrichment` Normalized business enrichment data may include: | Field | Type | Description | | ------------ | ---------------- | --------------------------------------------------- | | `names` | object, optional | Normalized business names | | `address` | object, optional | Normalized business address | | `geo` | object, optional | Geographic coordinates and precision | | `industry` | array, optional | Industry classifications | | `company` | object, optional | Company metadata such as legal form or year started | | `workforce` | object, optional | Employee counts and confidence | | `financials` | object, optional | Revenue and financial summary data | ### Documents `documents` contains expected document slots for a step. `additionalFiles` contains extra supporting uploads. Each resolved `file` can include: | Field | Type | Description | | ------------------ | ----------------- | --------------------------------------------------------- | | `id` | string | Public document ID | | `originalName` | string | Original uploaded filename | | `mimeType` | string | File MIME type | | `size` | number | File size in bytes | | `createdAt` | string, optional | Upload timestamp in ISO 8601 format | | `analysis.matches` | boolean, optional | Whether the uploaded file matched the expected document | | `url` | string | API path for retrieving a short-lived signed download URL | ## Document Access Files do not contain direct storage URLs. Instead, use the `file.url` value, which points to: ```http GET /kyb/case/{refId}/details/documents/{documentId} ``` This endpoint returns: ```json { "url": "https://storage.googleapis.com/...signed...", "expiresIn": 900 } ``` | Field | Type | Description | | ----------- | ------ | ------------------------------- | | `url` | string | Short-lived signed download URL | | `expiresIn` | number | URL lifetime in seconds | Fetch a fresh URL when the previous signed URL expires. ## AML Screening The `amlScreening` object contains: | Field | Type | Description | | --------- | ----- | -------------------------------------- | | `primary` | array | AML summaries for the primary business | | `related` | array | AML summaries for related businesses | Each AML summary can include: | Field | Type | Description | | ------------------- | ----------------- | ------------------------------------------ | | `refId` | string, optional | Reference ID for the screened entity | | `name` | string, optional | Display name used for screening | | `status` | string | Screening status | | `businessRole` | string | `primary` or `related` | | `businessName` | string, optional | Business name associated with the AML case | | `caseType` | string, optional | AML case type | | `sourceType` | string, optional | Source type for the AML case | | `ongoingMonitoring` | boolean, optional | Whether ongoing monitoring is enabled | | `totalHits` | number, optional | Total number of AML hits | | `createdAt` | string, optional | AML case creation timestamp | | `reviewedAt` | string, optional | AML review timestamp | ## Website Analysis If website analysis is available, the response may include: | Field | Type | Description | | ------------- | ---------------- | ------------------------------------------------------------ | | `domain` | string | Analyzed domain | | `status` | string, optional | Analysis status | | `initiatedAt` | string, optional | Analysis start timestamp | | `completedAt` | string, optional | Analysis completion timestamp | | `data` | object, optional | Provider-defined analysis data that is safe for customer use | ## Reopen History Each reopen entry contains: | Field | Type | Description | | ------------ | ---------------- | ---------------------------- | | `stepIds` | array of strings | IDs of the reopened steps | | `reason` | string, optional | Reason the case was reopened | | `reopenedAt` | string, optional | Reopen timestamp | ## Intentionally Excluded Fields The public contract intentionally excludes internal-only and provider-sensitive data, including: * Organization ownership data and MongoDB internals such as `__v` * Dashboard-only URLs * Raw provider enrichment payloads * Raw AML hit records, reviewer notes, and reviewer IDs * Provider correlation IDs inside website analysis payloads * Internal UBO user IDs * Internal step-state details * Session expiry data * Detailed document analysis internals such as confidence, reasoning, and markdown * Reopen actor IDs ## Notes * This endpoint is organization-scoped through the API key used on the request. * The response is additive to the existing raw case endpoints and is intended for stable customer integrations. * The full audit timeline is not included in this response. ## Error Responses ### 401 Unauthorized ```json { "statusCode": 401, "message": "Invalid API key" } ``` ### 404 Not Found ```json { "statusCode": 404, "message": "KYB case not found" } ``` ## Related Documentation * [KYB Overview](/docs/kyb-know-your-business/kyb-overview.md) - Understand the KYB verification flow * [Create KYB Case](/docs/kyb-know-your-business/kyb-create-case.md) - Create a case and generate the business verification link * [KYB Webhooks](/docs/kyb-know-your-business/kyb-webhooks.md) - Receive real-time KYB status updates