Skip to main content
POST

Authorizations

​
X-Auth-Client
string
header
required

Your workspace client id.

All calls must include four headers:

  • X-Auth-Client — your workspace client id
  • X-Auth-Timestamp — Unix seconds
  • X-Auth-Nonce — 16-byte random hex
  • X-Auth-Signature — hex(HMAC-SHA256( {client_id}:{timestamp}:{nonce}:{raw_body}, client_secret))

The playground computes the timestamp, nonce and signature for you.

​
X-Playground-Client-Secret
string
header
required

Your sandbox client secret. The playground uses it to sign the request in your browser and removes it before the request is sent. Never send your client secret as a header in your own integration.

Body

application/json

Exactly one of customer_id or customer is required.

​
terms_of_service_accepted
boolean
required

Must be true.

​
account_purpose
string

What the customer will use the card for.

Maximum string length: 100
​
annual_salary
string

Free text; must not be below expected_monthly_volume when both are numbers.

Maximum string length: 50
​
card_program
enum<string>

Defaults to prepaid.

Available options:
prepaid,
collateral
​
customer
object

Inline customer for KYC.

​
customer_id
string<uuid>

Existing customer. Provide this or customer.

​
employment_status
enum<string>

Employment status of the customer.

Available options:
employed,
self_employed,
unemployed,
retired,
student
​
expected_monthly_volume
string

Expected monthly spend on the card.

Maximum string length: 50
​
id_back_image
string

Back of the same document, same limits.

Maximum string length: 2796204
​
id_front_image
string

Front of the ID document, base64 or data URI, at most 2 MiB decoded. Used by the raw-identity flow only.

Maximum string length: 2796204
​
occupation
string

Code from GET /api/cards/kyc/occupations.

Maximum string length: 50
​
place_of_birth
string

Place of birth of the customer.

Maximum string length: 100
​
redirect_url
string

Where the hosted page returns the customer; checked against an allowlist.

Maximum string length: 2048
​
sumsub_share_token
string

Reusable-KYC share token. Only for companies on the company reusable-KYC flow, where it is required.

Maximum string length: 4096
​
webhook_url
string

Callback for the KYC outcome; defaults to the company webhooks.

Maximum string length: 2048

Response

OK

Successful responses are wrapped in this envelope, and so are errors a handler answers itself (request body and field validation, some not-found and conflict cases, ORG_NOT_ACTIVE): success is false and error carries a code and message. Errors raised by authentication and by the services behind a handler are a Problem instead.

​
success
boolean
required

true on success

​
timestamp
string<date-time>
required

When the response was written.

​
data
object

The payload; its shape is given per operation. Omitted when there is none.

​
error
object
​
message
string

Human-readable summary; omitted when empty.

​
metadata
object

List metadata. Page lists set page, per_page, total and total_pages; offset and cursor lists set limit, offset, has_more and next_cursor. Zero and empty fields are omitted, and metadata is absent when nothing is set.

​
request_id
string

Set on error envelopes: the request's correlation id (req_ followed by a UUID), the same value as the X-Correlation-ID response header. Quote it to support.