KYB requests

KYB ("Know Your Business") verifies the identity and structure of a business entity. The lifecycle is the same as KYC — create, upload supporting documents, submit, receive a decision — but with one extra step: you submit a KYB entity payload describing the company and its principals.

Create the request with type: "BUSINESS", then POST to the /kyb endpoint to attach the entity data.

The KYB extension

POST /api/v1/kyc/requests/:id/kyb    Scope: kyc:write

Attaches company details, directors, and ultimate beneficial owners (UBOs) to an existing BUSINESS request.

Request body

{
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "appointedAt": "2018-01-15"
    }
  ],
  "ubos": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "ownershipPercentage": 100
    }
  ]
}

Each director and UBO carries fullName, dateOfBirth, nationality, plus role-specific fields (appointedAt for directors, ownershipPercentage for UBOs).

Response (201)

{ "id": "req_...", "status": "PENDING_UPLOAD" }

The response also kicks off a registry lookup in the background — Certivant queries the relevant commercial register (Companies House for GB, OpenCorporates for many others) and stores the results against the request. Registry results are visible at GET /kyb.

Get KYB data

GET /api/v1/kyc/requests/:id/kyb    Scope: kyc:read

Returns the submitted entity data along with any registry lookup results.

Response

{
  "id": "kyb_...",
  "requestId": "req_...",
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [...],
  "ubos": [...],
  "registryLookup": {
    "status": "verified",
    "registryName": "Companies House",
    "registryUrl": "https://find-and-update.company-information.service.gov.uk/company/12345678",
    "registeredName": "Acme Holdings Ltd",
    "registeredAddress": "1 Example St, London",
    "status": "active",
    "incorporatedAt": "2018-01-15",
    "officerDelta": [],
    "raw": { ... }
  }
}

registryLookup.officerDelta lists any officers found in the registry but not declared in your directors array — useful for catching missing information.

Required documents

A BUSINESS request typically needs a different document set than an individual:

• CERTIFICATE_OF_INCORPORATION — proof the company exists.
• PROOF_OF_ADDRESS — for the registered office.
• GOVERNMENT_ID and SELFIE for each UBO and director (these go on per-applicant sub-requests in some configurations).
• COMPANY_OWNERSHIP_STRUCTURE — org chart or shareholder ledger.

The exact list comes back in pendingDocTypes on the request after you've attached the KYB entity. Your organization's KYB settings determine what's required.

Per-officer KYC sub-requests

Depending on your organization settings, Certivant may auto-create individual KYC sub-requests for each UBO and director. These appear as separate requests linked back to the parent BUSINESS request via the parentRequestId field. You upload documents to each sub-request the same way you upload to a standalone KYC request — see Documents.

graph LR
  Parent[BUSINESS request<br/>req_parent] --> Co[Company docs<br/>incorporation, address]
  Parent --> Ubo1[UBO 1 sub-request<br/>req_ubo1]
  Parent --> Ubo2[UBO 2 sub-request<br/>req_ubo2]
  Parent --> Dir1[Director sub-request<br/>req_dir1]
  Ubo1 --> Id1[GOVERNMENT_ID + SELFIE]
  Ubo2 --> Id2[GOVERNMENT_ID + SELFIE]
  Dir1 --> Id3[GOVERNMENT_ID + SELFIE]

The parent request stays in PENDING_UPLOAD until every sub-request is at least PROCESSING, then transitions through the same lifecycle as an individual request — PROCESSING → APPROVED / REJECTED / ESCALATED.

Submission and decision

Once company documents are uploaded and every sub-request is submitted, submit the parent:

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_parent/submit \
  -H "Authorization: Bearer ck_live_..."

The risk engine aggregates the parent's company checks plus every sub-request's verdict into a single decision. Webhook events fire for the parent — you don't need to separately track each sub-request unless you want a fine-grained view.

Errors

• 400 BAD_REQUEST — the request is not type BUSINESS. KYB endpoints only work on business requests.
• 409 CONFLICT — KYB data has already been attached. To change it, contact support — the entity data is part of the audit trail and can't be edited freely.

Related

• KYC requests — the underlying request endpoints, same lifecycle.
• Documents — uploading proof-of-incorporation and per-officer documents.
• Webhooks — the same kyc.request.* events apply.