API reference summary — CorePass Connector

Every endpoint on the KYC and KYB APIs in one table, with the hosts, the authentication scheme, the status vocabularies and the closed set of error reasons.

A summary, not a specification: every endpoint the integration touches, what it is for, and the vocabularies you will branch on. The detail — request bodies, response shapes, the verification recipes — is on the pages this one links back to.

Hosts and authentication #

API	Host	Authentication
Login and KYC	`https://auth-develop.corepassdev.eu` `https://auth-staging.corepassdev.eu`	The OAuth client CorePass issues you. The KYC endpoints identify the person by their Core ID in the body.
KYB merchant API	`https://api-develop.corepassdev.eu`	`Authorization: <api key>`, raw. Never `Bearer` — a prefixed key is refused as `apikey_invalid`.

Your own deployment is given its own hostnames; the ones above are the develop and staging environments as they appear in the integration documentation.

KYC and login endpoints #

Method	Path	What it does
POST	`/api/v1/blockchain/verified`	Which of the named items has this person verified? Answers with verifiedItems and unVerifiedItems.
POST	`/api/v1/kyc/qrcode`	Create a data-transfer request and get the QR code and link to show. Takes user, items, callback, statusCallback, expiration and the optional withoutQRCode.
POST	`/api/v1/kyc/status`	The latest status for a person and an item list. Complementary to the status callback; results cover the past month.
POST	`/api/v1/kyc/all-statuses`	Every status for a person and an item list, newest first, under AllStatuses. Results cover the past month.
POST	`/api/v1/blockchain/valid`	Are the values you hold still valid? Takes user and a list of fieldID, fieldValue and pepper; answers with valids and invalids.
POST	`/api/v1/loginsrv/check-register`	Polled by login.js with the login form; answers with the destination once the person has approved the sign-in.

Full detail on the KYC page.

KYB endpoints #

Method	Path	What it does
POST	`/api/v1/kyb/data-requests`	Ask a named business for fields. Idempotency-Key recommended.
GET	`/api/v1/kyb/data-requests/{requestId}`	Read a request and its status. Never returns a value.
POST	`/api/v1/kyb/data-requests/offers`	Mint a QR offer instead of naming a business. Idempotency-Key required.
GET	`/api/v1/kyb/data-requests/offers/{offerId}`	Poll an offer: OPEN, CLAIMED, EXPIRED or CANCELLED.
POST	`/api/v1/kyb/data-requests/{requestId}/redeliver`	Queue the events again, with the same event ids.
GET	`/api/v1/kyb/data-requests/{requestId}/deliveries`	Per-attempt webhook history.
GET	`/api/v1/kyb/data-requests/{requestId}/events`	The event stream, with the attestation while it is retained.
GET	`/api/v1/kyb/data-requests/{requestId}/release`	Pull the attestation. 404 not_released while the vote is open, 410 payload_expired after retention.
POST	`/api/v1/kyb/data-requests/quote`	Price a field list. Reserves nothing.
PUT	`/api/v1/kyb/webhook-endpoint`	Register the delivery URL. Returns the signing secret exactly once.
GET	`/api/v1/kyb/webhook-endpoint`	The current registration. Never carries the secret.
POST	`/api/v1/kyb/webhook-endpoint/rotate-secret`	Mint a new secret; the previous one stays valid for 24 hours.
POST	`/api/v1/kyb/webhook-endpoint/reactivate`	Clear a quarantine and send the backlog. 409 if it is not quarantined.
GET	`/api/v1/kyb/pricing`	The whole tier table, machine-readable, with every field and its tier.
GET	`/.well-known/kyb-jwks.json`	The attestation key set, with the active key id, version and vocabulary digest.

Signature endpoints #

These need the signature capability on your API key, which is default-deny and granted per organisation.

Method	Path	What it does
POST	`/api/v1/kyb/signature-requests`	Ask a named business to sign. Idempotency-Key required.
POST	`/api/v1/kyb/signature-requests/offers`	Mint a QR instead. Idempotency-Key required.
GET	`/api/v1/kyb/signature-requests/offers/{offerId}`	Poll an offer.
POST	`/api/v1/kyb/signature-requests/offers/{offerId}/cancel`	Withdraw an unclaimed offer.
GET	`/api/v1/kyb/signature-requests`	List, with limit, offset and a repeatable status filter.
GET	`/api/v1/kyb/signature-requests/{requestId}`	Read one.
POST	`/api/v1/kyb/signature-requests/{requestId}/cancel`	Withdraw a request the members have not finished.
GET	`/api/v1/kyb/signature-requests/{requestId}/deliveries`	Per-attempt webhook history.
GET	`/api/v1/kyb/signature-requests/{requestId}/events`	The event stream, with an after_seq cursor.
GET	`/api/v1/kyb/signature-requests/{requestId}/signature`	Pull the signature. 404 not_signed while the vote is open; no retention deadline.

Billing endpoints #

Method	Path	What it does
GET	`/api/v1/kyb/billing/account`	Your balance: total, spent, frozen and available, in CHF.
GET	`/api/v1/kyb/billing/charges`	The charge ledger, newest first, with limit and offset.

There is no top-up on the merchant API: paying is a dashboard action taken by a person, not something an API key should be able to do.

Status vocabularies #

Four different vocabularies are in play, and they do not share a casing convention. Getting this wrong is the most common cause of a comparison that silently never matches.

Where	Casing	Values
KYC transfer status, on the wire	lower case	`pending` through `finish_failed` — the sixteen states on the KYC page. Compare case-insensitively.
KYB request status	lower case	`pending_approval`, `action_proposed`, `released` / `signed`, `refused`, `cancelled`, `expired`, `failed`
KYB offer status	UPPER CASE	`OPEN`, `CLAIMED`, `EXPIRED`, `CANCELLED`
Ledger state	UPPER CASE	`RESERVED`, `SPENT`, `RELEASED`, `FAILED`, `DISABLED`

A request status and an offer status are two different things with two different vocabularies. And RELEASED in the ledger means the money went back to your credit, which is the opposite of a released data request.

Error shape and reasons #

Every refusal under the KYB API carries a machine-readable reason from a closed set, alongside a human message. Branch on the reason, never on the message.

The shape

{
  "success": false,
  "error": {
    "code": 422,
    "reason": "unknown_field",
    "message": "NOT_A_FIELD is not in the vocabulary"
  }
}

`malformed_request`	`apikey_missing`	`apikey_invalid`
`kyb_not_entitled`	`pii_not_entitled`	`business_not_found`
`business_not_verified`	`request_not_found`	`request_not_open`
`request_already_open`	`idempotency_key_conflict`	`no_webhook_endpoint`
`endpoint_not_quarantined`	`offer_not_found`	`offer_not_open`
`unknown_field`	`retired_field`	`not_released`
`payload_expired`	`rate_limited`	`entitlement_unavailable`
`verification_unavailable`	`not_implemented`	`internal_error`
`kyb_signature_not_entitled`	`not_signed`	`field_not_priced`
`insufficient_credit`	`no_credit_account`

Two do not follow the shape: insufficient_credit and no_credit_account are both 402, and their bodies carry up to three extra members — the required amount, the available amount and the quoted cents — beside the usual three. Read all three as optional: a missing one is missing, never a zero.

Headers #

Header	Direction	What it is
`Authorization`	You → CorePass	The KYB API key, raw and unprefixed.
`Idempotency-Key`	You → CorePass	1–128 printable ASCII, scoped to your client domain. Recommended on a data request, required on every offer and on both signature creates.
`Corepass-Signature`	CorePass → you	KYC. `t=` and `s=`; HMAC-SHA256 over the timestamp and the raw body.
`Corepass-KYB-Signature`	CorePass → you	KYB. `t=`, `v1=` and `kv=`, the last naming the secret version.
`Corepass-Event-Id`	CorePass → you	The ULID your dedupe keys on. Identical across retries.
`Corepass-Delivery-Attempt`	CorePass → you	This attempt's number, from 1. A header rather than a body member so the body stays byte-identical across retries.
`Corepass-Kyb-Api-Version`	CorePass → you	The KYB API version the delivery was produced by.