# Business verification (KYB)

`POST https://api-verify.secuveri.com/v1/kyb/cases` verifies a Swiss company. secuveri reads the commercial register through its official services (Zefix and the federal UID register): legal name, UID, legal form, seat, address, status (active, in liquidation, deleted), purpose, capital and the registered persons with their roles and signing authority, rebuilt from the company's SOGC publications. Signing texts such as "Kollektivunterschrift zu zweien" are read by a fixed grammar in German, French and Italian; a text it does not fully understand is never guessed and holds the case with `KYB_SIGNING_UNPARSED`. The company and every person are screened against the sanctions and PEP lists.

```shell
curl -X POST https://api-verify.secuveri.com/v1/kyb/cases \
  -H "x-api-key: $SECUVERI_API_KEY" \
  -H "Idempotency-Key: $KYB_REQUEST_ID" \
  -H "content-type: application/json" \
  -d '{"uid":"CHE-105.909.036","workflow_id":"$WORKFLOW_ID","reference":"customer-42"}'
```

- `workflow_id` is a published workflow with the Business Verification step. Its other steps (identity document, liveness, face match, AML…) are what each person's verification runs; its outcome settings and four-eyes option decide the case.
- Open by `uid`, or by `name` when exactly one company has that name (otherwise 409 `ambiguous_company` with candidates; `GET /v1/kyb/search?name=` lists them for free).
- Beneficial owners: for a GmbH the register shows the partners and their capital shares, so partners holding 25% or more are owner candidates. For an AG the shareholders are not public, so the applicant declares them: send the case's `declaration_url` to the applicant, or post the declaration to `/v1/kyb/cases/{id}/declaration`.
- Persons: `POST /v1/kyb/cases/{id}/persons/{personId}/verification` starts a verification of the workflow for a signatory or owner and returns its url; with `send_link` we email or text it. Joint signing (zu zweien) needs enough co-signers verified.
- A register extract can be uploaded to `/v1/kyb/cases/{id}/documents` for your reviewers.
- Each case is charged once, when the register found the company; each person's verification is charged like any verification.

| Status | Meaning |
| --- | --- |
| open | Waiting for persons' verifications, the declaration, a register extract or a signatory to verify (see `outstanding`) |
| review_required | A reason holds the case for your team |
| approved | Everything checked out, or a reviewer approved it |
| declined | A decline reason (deleted company, sanctions hit by default) or a reviewer declined it |

Reasons are `KYB_COMPANY_NOT_FOUND`, `KYB_COMPANY_INACTIVE`, `KYB_COMPANY_DELETED`, `KYB_NAME_MISMATCH`, `KYB_SANCTIONS_COMPANY`, `KYB_SANCTIONS_PERSON`, `KYB_PEP_PERSON`, `KYB_UBO_UNVERIFIED`, `KYB_SIGNATORY_UNVERIFIED`, `KYB_DECLARATION_MISSING`, `KYB_REGISTER_EXTRACT_MISSING` and `KYB_SIGNING_UNPARSED`; their actions are set in the workflow's outcome settings. Webhooks `kyb_case.completed`, `kyb_case.review_required` and `kyb_case.reviewed` carry `kyb_case_id`. A decided case carries `signed_result` (JWS, `typ` `kyb_case`) with identifiers and outcome only.

Limits: Switzerland only for now. Persons come from the SOGC publications Zefix holds (about the last ten years); for an older company `persons_complete` is false and the register extract or declaration fills the gap. The federal transparency register is not public, and Swiss registers publish no birth dates, so register persons are screened by name only.