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

x-api-key: YOUR_API_KEY

Path Parameters

Parameter	Type	Required	Description
refId	string	Yes	Your reference ID for the KYB case

Example Request

curl -X GET https://api.voveid.com/kyb/case/unique-business-ref-12345/details \
  -H "x-api-key: YOUR_API_KEY"

Response

Success Response

{
  "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": "[email protected]",
              "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:

GET /kyb/case/{refId}/details/documents/{documentId}

This endpoint returns:

{
  "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

{
  "statusCode": 401,
  "message": "Invalid API key"
}

404 Not Found

{
  "statusCode": 404,
  "message": "KYB case not found"
}

Related Documentation

• KYB Overview - Understand the KYB verification flow

• Create KYB Case - Create a case and generate the business verification link

• KYB Webhooks - Receive real-time KYB status updates