Open a business verification (KYB) case

POST/v1/kyb/cases

Looks the company up in the Swiss commercial register (Zefix and the UID register) by UID, or by name when exactly one company has that name, lists its registered persons with their roles and signing authority, derives beneficial owner candidates (GmbH partners holding 25% or more), and screens the company and its persons against the sanctions and PEP lists. workflow_id names a published workflow with the Business Verification step; its other steps are what each person's verification runs. Charged once per case when the register found the company (pricing: business-verification). Needs kyb:write. Send Idempotency-Key to get the same case back on retries for 24 hours.

Send your API key in the x-api-key header.

Headers

Idempotency-Keystring8–200 chars

Request bodyapplication/jsonrequired

uidstring
Swiss UID, CHE-123.456.789 or CHE123456789.
namestring
Company name; with a UID it is compared with the registered name (KYB_NAME_MISMATCH).
workflow_idstringuuidrequired
referencestring≤ 128 chars
Your id for the company; echoed back.
personsarray of object0–20 items
Show 4 child propertiesHide child properties
- registry_person_idstring
- emailstring
- phonestring
- send_linkany
  One ofemailsms
languageany
Language of legal form labels.
One ofdefriten

Responses

200The case opened earlier with this Idempotency-Key.
- idstringuuid
- objectstringalways "kyb_case"
- statusany
  One ofopenreview_requiredapproveddeclined
- reasonsarray of object
  Show 2 child propertiesHide child properties
  codestring
  actionany
  One ofreviewdecline
- outstandingarray of any
  What an open case waits for.
- companyobject | null
  Register data: uid, name, legalForm, seat, canton, address, status, purpose, capital, publications.
- uboobject | null
  status identified | partial | none_identified | not_public, threshold_pct, declaration_required.
- signing_rulesarray of object
- personsarray of object
  Registered and declared persons with roles, signing_mode, is_signatory, is_ubo, ownership_pct, verification (status, verification_id) and screening.
- company_screeningobject | null
- declarationobject | null
- documentsarray of object
- declaration_urlstring | null
- signed_resultstring
  Decided cases only, when result signing is configured.
201The case, plus declaration_url (the applicant's declaration link, shown once).
- idstringuuid
- objectstringalways "kyb_case"
- statusany
  One ofopenreview_requiredapproveddeclined
- reasonsarray of object
  Show 2 child propertiesHide child properties
  codestring
  actionany
  One ofreviewdecline
- outstandingarray of any
  What an open case waits for.
- companyobject | null
  Register data: uid, name, legalForm, seat, canton, address, status, purpose, capital, publications.
- uboobject | null
  status identified | partial | none_identified | not_public, threshold_pct, declaration_required.
- signing_rulesarray of object
- personsarray of object
  Registered and declared persons with roles, signing_mode, is_signatory, is_ubo, ownership_pct, verification (status, verification_id) and screening.
- company_screeningobject | null
- declarationobject | null
- documentsarray of object
- declaration_urlstring | null
- signed_resultstring
  Decided cases only, when result signing is configured.
400Invalid input.
401Missing, unknown or expired API key.
402The balance does not cover the company check.
403The key lacks the kyb:write scope, or its IP allowlist refuses the caller.
404No such workflow in your organization.
409Several companies have this name (ambiguous_company, with candidates), or the Idempotency-Key is in progress.
422Invalid UID, or the workflow has no Business Verification step.
429More than 60 business verification calls in a minute.
503The commercial register is unavailable (registry_unavailable); nothing was charged.

curl -X POST https://api-verify.secuveri.com/v1/kyb/cases \
  -H "x-api-key: $SECUVERI_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: signup-1042-retry-safe" \
  -d '{
  "workflow_id": "<published workflow id>"
}'

Response · 200

{
  "id": "0b8f4f5e-3c2a-4d1b-9e7f-6a5c4b3d2e1f",
  "object": "kyb_case",
  "status": "open",
  "reasons": [
    {
      "code": "invalid_request",
      "action": "review"
    }
  ],
  "outstanding": [
    "KYB_DECLARATION_MISSING"
  ],
  "company": null,
  "ubo": null,
  "signing_rules": [
    {}
  ],
  "persons": [
    {}
  ],
  "company_screening": null,
  "declaration": null,
  "documents": [
    {}
  ],
  "declaration_url": "<declaration url>",
  "signed_result": "eyJhbGciOiJFUzI1NiIsImtpZCI6Ii4uLiJ9.…"
}