Reference

POST /partner/v1/identity/checks

Run a KYC/AML identity check on the partner ring. Calls the identity provider, so sub-limited to 5 req/s. Returns a check reference; the result may arrive by webhook.

2 min read

POSTHTTP method

OAuthAuth

partnerRing

Endpoint

Method	`POST`
Path	`/partner/v1/identity/checks`
Ring	partner (OAuth)
Auth	OAuth

Request

A JSON body with the subject's identity details to verify. Requires identity:write and an Idempotency-Key.

Response

A JSON object with the check's reference and initial status. Because the check calls an external KYC/AML provider, the definitive result may follow asynchronously via a webhook or a subsequent read. Handle a pending state gracefully rather than blocking your flow on a synchronous result.

Errors & notes

Sub-limited to 5 req/s — each call hits the KYC/AML provider. A 422 for insufficient identity data; a 403 without identity:write. Idempotency applies so a retry does not run a duplicate check.

Frequently asked questions

Is the identity result synchronous?

Not always. The check calls an external KYC/AML provider, so the definitive result can arrive asynchronously by webhook. Handle a pending status rather than assuming an immediate answer.

Why the 5 req/s sub-limit?

Each check invokes an external identity provider, which is a metered, costly call. The sub-limit keeps that spend bounded; send an idempotency key so a retry does not run a second check.