KYB Cases

Endpoints for creating and retrieving KYB cases.

Create a new KYB case

post

https://demo-api.vivox.aihttps://portal-api.vivox.ai

/v1/kyb-cases

Required fields:

• legal_name - The legal name of the business

• jurisdiction_code - Two-letter ISO country code (e.g., CN, US, DE)

• reference_id - Your internal tracking reference

Assignment: If assignment is not provided, the case is assigned to the creator by default.

Website URLs: The API accepts multiple website URLs (website_urls), but currently only the first URL is used for analysis and displayed in the interface. The array format is retained for future compatibility.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

Creates a KYB case

legal_namestringRequired

The legal name of the business. Required

Example: Acme Holdings Ltd

company_numberstringOptional

The company registration number

Example: 07495895

website_urlsstring · uri[]Optional

Optional list of websites associated with the business. Important: For compatibility, this field accepts multiple URLs, but currently only the first URL in the array is processed and displayed in the Vivox interface. Additional URLs are ignored at this time. The array format is retained to allow future functionality without breaking changes.

Example: ["https://acme.com","https://blog.acme.com"]

jurisdiction_codestring · min: 2 · max: 2Required

Two-letter ISO jurisdiction code. Must exist in the jurisdictions list.

Example: CN

reference_idstringRequired

Your internal reference key for the case.

Example: CRM-CASE-12931

Responses

201

Successfully created

application/json

401

Not authenticated

application/json

422

Validation error

application/json

post

/v1/kyb-cases

HTTPcURLJavaScriptPython

POST /v1/kyb-cases HTTP/1.1
Host: demo-api.vivox.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 222

{
  "legal_name": "Acme Corporation Ltd",
  "company_number": "12345678",
  "jurisdiction_code": "CN",
  "website_urls": [
    "https://acme.com",
    "https://blog.acme.com"
  ],
  "reference_id": "CRM-2025-001",
  "assignment": {
    "email": "[email protected]"
  }
}

Full example with all optional fieldsCase assigned immediately by user_id

{
  "data": {
    "id": "f3b1a5c8-8a92-4f20-bb7a-2f0f4f7a6a10",
    "legal_name": "Acme Holdings Ltd",
    "company_number": "07495895",
    "jurisdiction_code": "CN",
    "reference_id": "CRM-CASE-12931",
    "website_urls": [
      "https://acme.com",
      "https://blog.acme.com"
    ],
    "status": "upload_required",
    "creator": {
      "id": "d35a68114-e5e4-48bc-af16-bed68f2f1550",
      "name": "Jane Doe",
      "email": "[email protected]"
    },
    "assignee": {
      "id": "d35a68114-e5e4-48bc-af16-bed68f2f1550",
      "name": "Jane Doe",
      "email": "[email protected]"
    },
    "created_at": "2025-10-25T12:45:20.000000Z"
  }
}

Get a KYB case by ID

get

https://demo-api.vivox.aihttps://portal-api.vivox.ai

/v1/kyb-cases/{kyb_case_id}

Retrieves detailed information about a specific KYB case.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

kyb_case_idstring · uuidRequired

The KYB case UUID.

Example: 019a51aa-6a43-7268-b9e1-3c53e8f6c8e9

Responses

200

Success

application/json

401

Not authenticated

application/json

404

Resource not found or access denied

application/json

get

/v1/kyb-cases/{kyb_case_id}

HTTPcURLJavaScriptPython

GET /v1/kyb-cases/{kyb_case_id} HTTP/1.1
Host: demo-api.vivox.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "id": "019a51fe-29ff-71bd-a7bb-7cf22a2d7fc0",
    "legal_name": "Acme Corporation Ltd",
    "company_number": "12345678",
    "jurisdiction_code": "CN",
    "reference_id": "CRM-2025-001",
    "website_urls": [
      "https://acme.com"
    ],
    "status": "in_progress",
    "creator": {
      "id": "00a68114-e5e4-48bc-af16-bed68f2f1550",
      "name": "Jane Doe",
      "email": "[email protected]"
    },
    "assignee": {
      "id": "954d25a4-0ec5-454e-8899-577dec5815c6",
      "name": "John Smith",
      "email": "[email protected]"
    },
    "created_at": "2025-11-05T03:10:02.000000Z"
  }
}