onboarding

Get KYB case (wizard state)

GET /v1/customers/{customerId}/kyb

• getKybCase
• API key scope onboarding:read
• Tenant any

Parameters

Responses

• 200 OK application/json

  Schema KybCase

  P10-T03: for sole_trader / individual the wizard asks for personal, (sole traders) the business company.tradingName and company.incorporationCountry, expected activity and the clean documents kyb_person_id + kyb_proof_of_address; ownership is always complete. The KYC applicant is an individual applicant (the operator's individual level) created from personal; its review drives the case like a company review, and approval needs it GREEN when kyb.requireAllPersonsVerified is on (409 kyc_incomplete).

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • status KybCaseStatusrequiredread-only

    Fields of status

    KybCaseStatus

  • provider KycProviderIdrequired

  • applicantId string | nullread-only

  • company object

    Fields of company

    • legalName string

    • tradingName string | null

    • registrationNumber string | null

    • incorporationCountry CountryCode

    • incorporationDate Date | null

    • legalForm string | null

    • website string | null (uri)

    • industryCode string | null

      SIC/NACE code.

    • taxId string | null

  • expectedActivity object

    Fields of expectedActivity

    • monthlyVolume Money | null

    • monthlyTransactions integer | null

      min 0

    • currencies array of CurrencyCode

    • countries array of CountryCode

    • purpose string | null

      max length 1000

    • sourceOfFunds string | null

      max length 1000

  • steps objectrequired

    Wizard completion flags.

    Fields of steps

    • company boolean

    • addresses boolean

    • ownership boolean

    • activity boolean

    • documents boolean

    • personal boolean

      Sole traders and individuals only: the personal details are complete.

  • result object | null

    KYC provider outcome (read-only; staff only for details).

    Fields of result

    • reviewAnswer string | null

      One of: "green", "red", "retry"

    • screeningHits integer

      min 0

    • details KybProviderResult

  • infoRequested string | null

  • submittedAt Timestamp | null

  • reviewedAt Timestamp | null

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • updatedAt Timestampread-only

    Fields of updatedAt

    Timestamp

  • customerType CustomerTyperead-only

    Fields of customerType

    CustomerType

  • personal KybPersonal

  • mode OnboardingModeread-only

    Fields of mode

    OnboardingMode

• 304 Not modified (`If-None-Match` matched).
• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/customers/{customerId}/kyb" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/customers/{customerId}/kyb", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/customers/{customerId}/kyb",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()