KYB Cases

Endpoints for creating and retrieving KYB cases.

Create a new KYB case

post
/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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

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
post
/v1/kyb-cases
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]"
  }
}
{
  "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
/v1/kyb-cases/{kyb_case_id}

Retrieves detailed information about a specific KYB case.

Authorizations
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
get
/v1/kyb-cases/{kyb_case_id}
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"
  }
}
PreviousWelcome to Vivox APINextUsers and Jurisdictions

Last updated