Skip to main content
API docs by Redocly

zyphe-sdk (3.10.0)

Download OpenAPI specification:Download

SDK: Verification Requests

Create a verification session

Creates a verification request for a user on a flow and returns what the client needs to open it: the verification request, the session token and access signature for the hosted flow, and the slug of the step to start from. Identify the user by email, by an external ID, or by a wallet.

Authorizations:
x-api-key
path Parameters
flow_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Flow ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
Array of any (VerificationIdentifierCredential)

Credentials to enable for this identity (e.g. wallet, magic-link). The first Wallet entry determines the zid; all entries are provisioned on identity creation.

email
string or null

Email address of the user. Used for notifications and as the zid when no wallet credential is provided.

object or null

Arbitrary key-value metadata to attach to this verification request.

null or SdkSessionWebhookPayload (object)

Responses

Request samples

Content type
application/json
{
  • "credentials": [
    ],
  • "email": "string",
  • "customData": {
    },
  • "webhook": { }
}

Response samples

Content type
application/json
{
  • "email": "string",
  • "flowSlug": "string",
  • "flowStepSlug": "string",
  • "isSandbox": true,
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "sessionWebhook": { },
  • "verificationRequest": {
    },
  • "zid": "string",
  • "zypheAccessSig": "string",
  • "zypheToken": "string"
}

Get the next verification step

Returns the next step the user has to complete on the flow, or isCompleted: true when there is none. Identify the user by email, by an external ID, or by a wallet. Use it to decide which step to present, then call the matching submit endpoint.

Authorizations:
x-api-key
path Parameters
flow_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Flow ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

email
string or null

Email address of the user whose verification progress should be queried.

null or CredentialType (string)

Credential type for wallet or external-ID based resolution (WALLET or EXTERNAL_ID).

null or SiwxChain (string)

Wallet chain. Required when credentialType is WALLET.

address
string or null

Wallet address. Required when credentialType is WALLET.

externalId
string or null

External identifier. Required when credentialType is EXTERNAL_ID.

Responses

Response samples

Content type
application/json
{
  • "customData": {
    },
  • "executedActions": [
    ],
  • "flowResultId": "f842deda-7b24-4524-8232-f33c5f261770",
  • "isCompleted": true,
  • "nextStep": { }
}

Submit identity document images

Submits the front (and, for two-sided documents, back) images of an identity document for verification. Call this after next-step returns a document verification step.

Authorizations:
x-api-key
path Parameters
flow_id
required
string <uuid>

Flow ID

verification_request_id
required
string <uuid>

Verification Request ID

query Parameters
sandbox
boolean

Use sandbox environment

Request Body schema: application/json
required
allowedDocumentTypes
Array of integers <int64> [ items <int64 > ]
browser
string or null
countryCode
required
string
forceDocumentType
integer or null <int64>
Array of objects (InputImage)

One front image and an optional back image, base64-encoded.

interviewId
string or null

Session ID of a hosted document-capture session, as returned when the session was created. Send it together with sessionToken to have the results fetched from the capture session.

platform
string or null
provinceCode
string or null
sessionToken
string or null

Session token for a hosted document-capture session, as returned when the session was created. Send it together with interviewId (and no images) to have the results fetched from the capture session instead of scanning uploaded images.

Array of objects (InputImage)

Uncropped originals accompanying images, base64-encoded. Optional: omit for clients that only submit cropped images. Stored in S3 next to the doc-scan logs under their own retention window and never written to the vault or fed to the extraction provider — see ProcessIdentityDocumentPayload::validate_images. Each entry's pageIndex must have a matching entry in images (an uncropped back with no cropped back is a client bug).

Responses

Request samples

Content type
application/json
{
  • "allowedDocumentTypes": [
    ],
  • "browser": "string",
  • "countryCode": "string",
  • "forceDocumentType": 0,
  • "images": [
    ],
  • "interviewId": "string",
  • "platform": "string",
  • "provinceCode": "string",
  • "sessionToken": "string",
  • "uncroppedImages": [
    ]
}

Response samples

Content type
application/json
{
  • "attemptsCount": 0,
  • "jobId": "string",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

Get the liveness challenge

Returns the liveness challenge for the current verification request, with the upload URLs for the capture. Use it to present the liveness capture to the user.

Authorizations:
x-api-key
path Parameters
flow_id
required
string <uuid>

Flow ID

verification_request_id
required
string <uuid>

Verification Request ID

query Parameters
sandbox
boolean

Use sandbox environment

Responses

Response samples

Content type
application/json
No sample

Submit the liveness capture

Submits the liveness capture (selfie or video) for processing. Call this after completing the challenge returned by liveness-challenge.

Authorizations:
x-api-key
path Parameters
flow_id
required
string <uuid>

Flow ID

verification_request_id
required
string <uuid>

Verification Request ID

query Parameters
sandbox
boolean

Use sandbox environment

Request Body schema: application/json
required
challengeId
required
string <uuid>
movementImagesQuantity
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "challengeId": "007cfdcc-a46d-4340-a4c6-216ec2e4009c",
  • "movementImagesQuantity": 0
}

Response samples

Content type
application/json
{
  • "jobId": "string",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

Submit the document selection

Submits the user's document selection (country and document type) to complete the document selection step. Call this after next-step returns a document-selection step, then call next-step again to proceed.

Authorizations:
x-api-key
path Parameters
flow_id
required
string <uuid>

Flow ID

verification_request_id
required
string <uuid>

Verification Request ID

query Parameters
sandbox
boolean

Use sandbox environment

Request Body schema: application/json
required
country
string or null

ISO 3166-1 alpha-2 country code of the document to be verified (e.g. "US", "GB"). Optional — omit to allow any country.

documentType
integer or null <int64>

Numeric document type identifier. Optional — omit to allow any document type.

Responses

Request samples

Content type
application/json
{
  • "country": "string",
  • "documentType": 0
}

Response samples

Content type
application/json
{
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

SDK: Organizations

List flow results

Lists the flow results of one flow, identified by its slug, with pagination and filters.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

flow_slug
required
string

Flow slug to scope results to

query Parameters
object (Pagination)
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "page": [
    ],
  • "totalCount": 0
}

Search flow results

Tells whether a user passed a verification. Looks flow results up by the user's email, by the custom data attached when the verification request was created, or by both, and returns the status of each match, most recently updated first. passed is true once the user completed the flow successfully.

At least one of email and customData is required. A user who never started a verification gives an empty page.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
customData
object or null

Custom data the flow result has to carry: every key given here has to be present with the same value. Keys you leave out are not compared.

email
string or null

Email address of the user, as given when the verification request was created. Matched exactly, ignoring letter case.

flowSlug
string or null

Limits the search to one flow. Without it, every flow of the organization is searched.

skip
integer <int32> >= 0
take
integer <int32> >= 0

Responses

Request samples

Content type
application/json
{
  • "customData": { },
  • "email": "jane.doe@example.com",
  • "flowSlug": "kyc-flow",
  • "skip": 0,
  • "take": 20
}

Response samples

Content type
application/json
{
  • "page": [
    ],
  • "totalCount": 0
}

Get flow result details

Returns one flow result: who it belongs to, its status, and the result of every step the user completed (document verification, liveness, proof of address, screening, forms, KYB and the others). The per-step result endpoints return each step's full detail.

The flow result is one of this organization's, or a KYC Passport result another organization shared with it: the result named by a kyc_passport.verification.updated notification. The same holds for the per-step result endpoints.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

flow_slug
required
string
Example: kyc-flow

The slug of the flow

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "amlResults": [
    ],
  • "assignedRiskTags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "customData": {
    },
  • "dvResults": [
    ],
  • "flow": { },
  • "flowSlug": "string",
  • "formResults": [
    ],
  • "geolocationResults": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "identity": { },
  • "jdmData": {
    },
  • "kybResults": [
    ],
  • "organization": { },
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "phoneResults": [
    ],
  • "poaResults": [
    ],
  • "reviewSuggestion": { },
  • "riskScorePercent": 0,
  • "spidResults": [
    ],
  • "status": "PENDING",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "walletResults": [
    ]
}

Get document verification result details

Returns the full result of one document verification step, with the document images and the data read from the document.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

flow_slug
required
string
Example: flow-slug

The slug of the flow

dv_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the DV result

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "errorTag": "unexpected",
  • "message": "string"
}

Download the KYC report of a document verification result

Returns the report of one document verification as a PDF: its outcome and every check it was held against, the data read from the document, the document images, the device and session, the person's AML screenings and an audit trail, with the verification data attached to the PDF as JSON. locale picks the language: en, it, de, es, fr or pt; any other prints in English. The report is generated on each request and states when it was generated.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

flow_slug
required
string
Example: flow-slug

The slug of the flow

dv_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the DV result

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "errorTag": "unexpected",
  • "message": "string"
}

Get proof of address result details

Returns the full result of one proof of address step, with the address document the user uploaded and the data read from it.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

flow_slug
required
string
Example: flow-slug

The slug of the flow

poa_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the POA result

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "errorTag": "unexpected",
  • "message": "string"
}

Get wallet result details

Returns the result of one wallet step: the wallet address and chain the user proved they control, the signed message, and the step's status.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

flow_slug
required
string
Example: flow-slug

The slug of the flow

wallet_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the wallet result

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "flowResultId": "f842deda-7b24-4524-8232-f33c5f261770",
  • "flowStep": { },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "message": "string",
  • "reason": "string",
  • "signature": "string",
  • "status": "PASSED",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4",
  • "walletAddress": "string",
  • "walletChain": "string"
}

Get phone result details

Returns the result of one phone step: the phone number the user verified and the step's status.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

flow_slug
required
string
Example: flow-slug

The slug of the flow

phone_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the phone result

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "documentId": "4704590c-004e-410d-adf7-acb7ca0a7052",
  • "flowResultId": "f842deda-7b24-4524-8232-f33c5f261770",
  • "flowStep": { },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "phoneNumberE164": "string",
  • "phoneNumberLast4": "string",
  • "status": "PASSED",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

Get form result details

Returns the answers the user gave in one form step, section by section, with the step's status and any risk tags the answers assigned.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

flow_slug
required
string
Example: flow-slug

The slug of the flow

form_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the form result

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "assignedRiskTags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "flowResultId": "f842deda-7b24-4524-8232-f33c5f261770",
  • "flowStep": { },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "form": { },
  • "formId": "126460ed-49b2-4c69-849a-bd8904ec5d8f",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "reason": { },
  • "riskFactorKeys": [
    ],
  • "sections": [
    ],
  • "status": "PASSED",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

Get flow result details (deprecated) Deprecated

Deprecated. Use "Get flow result details", which also takes the flow slug.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "amlResults": [
    ],
  • "assignedRiskTags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "customData": {
    },
  • "dvResults": [
    ],
  • "flow": { },
  • "flowSlug": "string",
  • "formResults": [
    ],
  • "geolocationResults": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "identity": { },
  • "jdmData": {
    },
  • "kybResults": [
    ],
  • "organization": { },
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "phoneResults": [
    ],
  • "poaResults": [
    ],
  • "reviewSuggestion": { },
  • "riskScorePercent": 0,
  • "spidResults": [
    ],
  • "status": "PENDING",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "walletResults": [
    ]
}

Get document verification result details (deprecated) Deprecated

Deprecated. Use "Get document verification result details", which also takes the flow slug.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

dv_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the DV result

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "errorTag": "unexpected",
  • "message": "string"
}

Get proof of address result details (deprecated) Deprecated

Deprecated. Use "Get proof of address result details", which also takes the flow slug.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the organization

flow_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the flow result

poa_result_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The ID of the POA result

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "errorTag": "unexpected",
  • "message": "string"
}

SDK: KYB

Send a UBO KYC reminder

Sends, or sends again, the email that invites one of the case's beneficial owners to complete their identity verification (KYC). The owner is given by their position in the ubos list that "Read a KYB case's officers" returns, starting from 0. Only an owner with an email can be invited. Useful when the flow does not send these invitations automatically.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

recipient_index
required
integer >= 0

Index of the UBO to send the KYC email to, matching the order in uboDefinitions

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "enqueued": true
}

Add UBOs to a KYB case (deprecated) Deprecated

Deprecated. Use POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/ubos instead. It takes the same body, and answers with the case's UBOs and directors after the change rather than the whole KYB result.

Adds one or more ultimate beneficial owners to an existing KYB case and answers with the KYB result.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

The ID of the KYB result — the id of its case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
required
Array of objects (AddKybPersonInput)
Array
country
required
string
dateOfBirth
required
string
email
string or null

When present, the person is sent a KYC invitation and must complete full KYC for the KYB to be approvable. When absent, the person is screened by name only (AML) and is not notified — a clean name-AML result is sufficient (and required) for that person.

firstName
required
string
gender
required
string
lastName
required
string

Responses

Request samples

Content type
application/json
{
  • "persons": [
    ]
}

Response samples

Content type
application/json
{
  • "assignedAt": "2019-08-24T14:15:22Z",
  • "assignedToIdentityId": "4320f3c3-8ca3-46ff-91aa-ad418c7a1fed",
  • "businessInfoRequiredFields": [
    ],
  • "businessInformation": { },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentChecks": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": { },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "formAnswers": [
    ],
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": { },
  • "pepAndSanctionsStatus": "REVIEW",
  • "reason": "string",
  • "report": "string",
  • "status": "ACQUIRING",
  • "uboDefinitions": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

Remove a UBO from a KYB case (deprecated) Deprecated

Deprecated. Use DELETE /sdk/organizations/{organization_id}/kyb-cases/{case_id}/ubos/{person_id} instead. It takes the same body, and answers with the case's UBOs and directors after the change rather than the whole KYB result.

Removes an ultimate beneficial owner from a KYB case by their stable id and answers with the KYB result.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

The ID of the KYB result — the id of its case

person_id
required
string <uuid>

Stable id of the UBO to remove

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "assignedAt": "2019-08-24T14:15:22Z",
  • "assignedToIdentityId": "4320f3c3-8ca3-46ff-91aa-ad418c7a1fed",
  • "businessInfoRequiredFields": [
    ],
  • "businessInformation": { },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentChecks": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": { },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "formAnswers": [
    ],
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": { },
  • "pepAndSanctionsStatus": "REVIEW",
  • "reason": "string",
  • "report": "string",
  • "status": "ACQUIRING",
  • "uboDefinitions": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

Add directors to a KYB case (deprecated) Deprecated

Deprecated. Use POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/directors instead. It takes the same body, and answers with the case's UBOs and directors after the change rather than the whole KYB result.

Adds one or more directors to an existing KYB case and answers with the KYB result.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

The ID of the KYB result — the id of its case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
required
Array of objects (AddKybPersonInput)
Array
country
required
string
dateOfBirth
required
string
email
string or null

When present, the person is sent a KYC invitation and must complete full KYC for the KYB to be approvable. When absent, the person is screened by name only (AML) and is not notified — a clean name-AML result is sufficient (and required) for that person.

firstName
required
string
gender
required
string
lastName
required
string

Responses

Request samples

Content type
application/json
{
  • "persons": [
    ]
}

Response samples

Content type
application/json
{
  • "assignedAt": "2019-08-24T14:15:22Z",
  • "assignedToIdentityId": "4320f3c3-8ca3-46ff-91aa-ad418c7a1fed",
  • "businessInfoRequiredFields": [
    ],
  • "businessInformation": { },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentChecks": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": { },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "formAnswers": [
    ],
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": { },
  • "pepAndSanctionsStatus": "REVIEW",
  • "reason": "string",
  • "report": "string",
  • "status": "ACQUIRING",
  • "uboDefinitions": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

Remove a director from a KYB case (deprecated) Deprecated

Deprecated. Use DELETE /sdk/organizations/{organization_id}/kyb-cases/{case_id}/directors/{person_id} instead. It takes the same body, and answers with the case's UBOs and directors after the change rather than the whole KYB result.

Removes a director from a KYB case by their stable id and answers with the KYB result.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

The ID of the KYB result — the id of its case

person_id
required
string <uuid>

Stable id of the director to remove

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "assignedAt": "2019-08-24T14:15:22Z",
  • "assignedToIdentityId": "4320f3c3-8ca3-46ff-91aa-ad418c7a1fed",
  • "businessInfoRequiredFields": [
    ],
  • "businessInformation": { },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentChecks": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": { },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "formAnswers": [
    ],
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": { },
  • "pepAndSanctionsStatus": "REVIEW",
  • "reason": "string",
  • "report": "string",
  • "status": "ACQUIRING",
  • "uboDefinitions": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

Read a KYB case's officers

The ultimate beneficial owners and the directors of the case, each with the stable id the officer routes address them by.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
  • "directors": [
    ],
  • "ubos": [
    ]
}

Add UBOs to a KYB case

Adds one or more ultimate beneficial owners to an existing KYB case and answers with the case's officers as they stand after the change.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
required
Array of objects (AddKybPersonInput)
Array
country
required
string
dateOfBirth
required
string
email
string or null

When present, the person is sent a KYC invitation and must complete full KYC for the KYB to be approvable. When absent, the person is screened by name only (AML) and is not notified — a clean name-AML result is sufficient (and required) for that person.

firstName
required
string
gender
required
string
lastName
required
string

Responses

Request samples

Content type
application/json
{
  • "persons": [
    ]
}

Response samples

Content type
application/json
{
  • "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
  • "directors": [
    ],
  • "ubos": [
    ]
}

Remove a UBO from a KYB case

Removes an ultimate beneficial owner from a KYB case by their stable id and answers with the case's officers as they stand after the change.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

person_id
required
string <uuid>

Stable id of the UBO to remove

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
  • "directors": [
    ],
  • "ubos": [
    ]
}

Add directors to a KYB case

Adds one or more directors to an existing KYB case and answers with the case's officers as they stand after the change.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
required
Array of objects (AddKybPersonInput)
Array
country
required
string
dateOfBirth
required
string
email
string or null

When present, the person is sent a KYC invitation and must complete full KYC for the KYB to be approvable. When absent, the person is screened by name only (AML) and is not notified — a clean name-AML result is sufficient (and required) for that person.

firstName
required
string
gender
required
string
lastName
required
string

Responses

Request samples

Content type
application/json
{
  • "persons": [
    ]
}

Response samples

Content type
application/json
{
  • "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
  • "directors": [
    ],
  • "ubos": [
    ]
}

Remove a director from a KYB case

Removes a director from a KYB case by their stable id and answers with the case's officers as they stand after the change.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

person_id
required
string <uuid>

Stable id of the director to remove

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
  • "directors": [
    ],
  • "ubos": [
    ]
}

Approve a KYB result (deprecated) Deprecated

Deprecated. Use POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/decision instead. Send outcome: APPROVED, with reason, reasonCode and dueDiligenceLevel as here. It answers with the decision rather than the KYB result.

Approves the company's KYB case. The decision is recorded as taken with your API key. The case must have completed its steps and have no unresolved screening match; otherwise the request fails with 400 and lists what is missing. An approved case cannot be decided again.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

KYB result ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
null or DueDiligenceLevel (string)
reason
string or null

Optional reason / summary for the approval decision. Stored on the KYB result and visible in the audit trail.

null or KybCaseDecisionReasonCode (string)

Responses

Request samples

Content type
application/json
{
  • "dueDiligenceLevel": { },
  • "reason": "string",
  • "reasonCode": { }
}

Response samples

Content type
application/json
{
  • "assignedAt": "2019-08-24T14:15:22Z",
  • "assignedToIdentityId": "4320f3c3-8ca3-46ff-91aa-ad418c7a1fed",
  • "businessInfoRequiredFields": [
    ],
  • "businessInformation": { },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentChecks": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": { },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "formAnswers": [
    ],
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": { },
  • "pepAndSanctionsStatus": "REVIEW",
  • "reason": "string",
  • "report": "string",
  • "status": "ACQUIRING",
  • "uboDefinitions": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4",
  • "decisionProposal": { }
}

Reject a KYB result (deprecated) Deprecated

Deprecated. Use POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/decision instead. Send outcome: REJECTED with the reason. It answers with the decision rather than the KYB result.

Rejects the company's KYB case with the reason you send. The decision is recorded as taken with your API key. A rejected case cannot be decided again.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

KYB result ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
reason
required
string

Why the company is rejected. Required, and never blank.

null or KybCaseDecisionReasonCode (string)

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "reasonCode": { }
}

Response samples

Content type
application/json
{
  • "assignedAt": "2019-08-24T14:15:22Z",
  • "assignedToIdentityId": "4320f3c3-8ca3-46ff-91aa-ad418c7a1fed",
  • "businessInfoRequiredFields": [
    ],
  • "businessInformation": { },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentChecks": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": { },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "formAnswers": [
    ],
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": { },
  • "pepAndSanctionsStatus": "REVIEW",
  • "reason": "string",
  • "report": "string",
  • "status": "ACQUIRING",
  • "uboDefinitions": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4",
  • "decisionProposal": { }
}

Request a KYB document

Asks the business for one more document on a KYB case and returns the request. The document must be one the flow marks as on demand; a document the flow already requires upfront is refused. The business is notified by email.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
body
string or null

Optional email body; defaults to a generated body referencing the document.

description
string or null

Optional description shown to the client; defaults to a generated message.

documentKey
required
string

Catalog key of the on-demand document to request (must be on-demand for this country).

recipientEmail
string or null

Optional recipient override; defaults to the business contact email.

subject
string or null

Optional email subject; defaults to a generated subject referencing the document.

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "description": "string",
  • "documentKey": "string",
  • "recipientEmail": "string",
  • "subject": "string"
}

Response samples

Content type
application/json
{
  • "clarificationFields": [
    ],
  • "clarificationResponse": { },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "documentName": "string",
  • "fieldStatuses": {
    },
  • "fulfilledAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "kybResultId": "f5562446-1011-4206-8c94-acf89f06e857",
  • "presignedUrl": "string",
  • "previousValues": {
    },
  • "requestType": "STANDARD",
  • "requestedByIdentityId": "bff67664-4117-4397-bb6b-0a1426d25791",
  • "reviewReason": { },
  • "status": "PENDING",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "uploadedFilename": "string",
  • "uploadedS3Key": "string"
}

Read a KYB case

Returns a KYB case as your dashboard shows it: its status, due-diligence level and risk rating, who it is assigned to, what it is waiting on, and its decision history. The case ID is the same as the KYB result ID.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "assignment": { },
  • "caseType": "ONBOARDING",
  • "companyKey": "string",
  • "contactEmail": "string",
  • "country": "string",
  • "coverage": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "decision": { },
  • "dueDiligenceLevel": "SIMPLIFIED",
  • "episode": { },
  • "flags": [
    ],
  • "flowResultId": "f842deda-7b24-4524-8232-f33c5f261770",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "legalName": "string",
  • "nextAction": "string",
  • "openedByIdentityId": "cd6929c4-1852-435b-b073-b09e3210ebf2",
  • "origin": "END_USER",
  • "rating": { },
  • "registrationNumber": "string",
  • "status": "OPEN",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "waitingOn": { },
  • "episodes": [
    ]
}

Download a KYB case's report

The case's KYB report as a PDF: company, activity, directors, ownership and beneficial owners, screening, adverse media, documents and sources, as the case stands at the time of the request. The report is identified by a hash of its content, returned as ETag: send it back as If-None-Match to get 304 when nothing in the report has changed.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

header Parameters
If-None-Match
string or null

The ETag of a report already held

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "errorTag": "unexpected",
  • "message": "string"
}

Decide a KYB case

Approves or rejects a KYB case. The decision is recorded as taken with your API key, and is final: a decided case cannot be decided again.

  • An approval needs the case to be ready for review (READY_FOR_REVIEW).
  • A rejection needs a reason.
  • Answers 200 with the decision. When your organization's approval rules require a second signature, it answers 202 instead: the decision waits until a team member with the required role confirms it in the dashboard.
Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

case_id
required
string <uuid>

The ID of the KYB case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
confirmingProposalId
string or null <uuid>

The standing proposed decision this act is the second signature on.

Where the organization's approval matrix asks for two signatures, the first act answers 202 with decisionProposal; sending its id back here is what closes the case. The confirmer must be a different person holding a decider role, and the proposal lapses rather than being honoured if the state it pinned has moved.

null or DueDiligenceLevel (string)
outcome
required
string (KybCaseDecisionOutcome)
Enum: "APPROVED" "REJECTED"

APPROVED | REJECTED. An approval needs READY_FOR_REVIEW; a rejection is also accepted from ACTION_REQUIRED, and then needs a reason.

reason
string or null

Mandatory on every rejection, and on an approval resting on a recorded exception or on a held match; optional on a clean approval. A blank string is no reason.

null or KybCaseDecisionReasonCode (string)

Responses

Request samples

Content type
application/json
{
  • "confirmingProposalId": "3715f698-90fb-453e-aa44-1ffb31b0b5be",
  • "dueDiligenceLevel": { },
  • "outcome": "APPROVED",
  • "reason": "string",
  • "reasonCode": { }
}

Response samples

Content type
application/json
{
  • "decidedAt": "2019-08-24T14:15:22Z",
  • "decisionId": "caa985ad-f12f-4ef1-943f-c1812738ec7a",
  • "decisionProposal": { },
  • "outcome": "APPROVED",
  • "reportVersionId": "8f554eac-f5be-4229-b932-cf9099332331",
  • "statusAfter": { },
  • "statusBefore": { }
}

Send a UBO KYC reminder (deprecated) Deprecated

Deprecated. Use POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/reminders/ubo/{recipient_index} instead: it does the same, addressed by the case ID.

Sends, or sends again, the email that invites one of the case's beneficial owners to complete their identity verification (KYC). The owner is given by their position in the ubos list that "Read a KYB case's officers" returns, starting from 0. Only an owner with an email can be invited. Useful when the flow does not send these invitations automatically.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

The ID of the KYB result, which is also the ID of its case

recipient_index
required
integer >= 0

Index of the UBO to send the KYC email to, matching the order in uboDefinitions

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "enqueued": true
}

Request a KYB document (deprecated) Deprecated

Deprecated. Use POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/document-requests/on-demand instead: it does the same, addressed by the case ID.

Asks the business for one more document on a KYB case and returns the request. The document must be one the flow marks as on demand; a document the flow already requires upfront is refused. The business is notified by email.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

The ID of the KYB result, which is also the ID of its case

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
body
string or null

Optional email body; defaults to a generated body referencing the document.

description
string or null

Optional description shown to the client; defaults to a generated message.

documentKey
required
string

Catalog key of the on-demand document to request (must be on-demand for this country).

recipientEmail
string or null

Optional recipient override; defaults to the business contact email.

subject
string or null

Optional email subject; defaults to a generated subject referencing the document.

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "description": "string",
  • "documentKey": "string",
  • "recipientEmail": "string",
  • "subject": "string"
}

Response samples

Content type
application/json
{
  • "clarificationFields": [
    ],
  • "clarificationResponse": { },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "documentName": "string",
  • "fieldStatuses": {
    },
  • "fulfilledAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "kybResultId": "f5562446-1011-4206-8c94-acf89f06e857",
  • "presignedUrl": "string",
  • "previousValues": {
    },
  • "requestType": "STANDARD",
  • "requestedByIdentityId": "bff67664-4117-4397-bb6b-0a1426d25791",
  • "reviewReason": { },
  • "status": "PENDING",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "uploadedFilename": "string",
  • "uploadedS3Key": "string"
}

SDK: AML

Screen a person or company (AML)

Screens a person or a company against sanctions, politically exposed persons (PEP) and other watchlists, and returns the matching entries in the format named by format. The result is returned as found: no risk score is computed and nothing is stored. Each call is charged.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
required
object (SdkAmlScreenQuery)

Search criteria for an AML screening. Every field is an optional string; provide at least one. The more fields you fill in, the more precise the matching. Result-only data (sanctions, topics, positions held) cannot be used as search input.

subjectType
string (AmlSubjectType)
Enum: "PERSON" "COMPANY"

The screened subject of an AML result. DTO mirror of the DB AmlSubjectType entity enum (converted via From<entities::AmlSubjectType>); lets consumers tell a company AML result from a person one. Defaults to Person (every result predating this field was a person).

Responses

Request samples

Content type
application/json
{
  • "query": {
    },
  • "subjectType": "PERSON"
}

Response samples

Content type
application/json
{
  • "entities": [
    ],
  • "format": "string",
  • "provider": "string"
}

SDK: TIN Check

List TIN checks

Lists your organization's TIN checks, newest first, whether they were run from the dashboard, with an API key, or on a KYB submission. Each check comes with its results, and the TIN is masked to its last four digits. Filter by flowResultId to get the checks of a KYB result.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

query Parameters
take
integer <int64> >= 0

Page size (default 50, max 200).

skip
integer <int64> >= 0
verificationRequestId
string <uuid>

Only the checks run on this KYB anchor's verification request.

flowResultId
string <uuid>

Only the checks run on this flow result's verification requests: the checks of its KYB result. A KYB result of a split flow names no verification request of its own, so this is how the dashboard finds them. Ignored when verificationRequestId is given.

sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Run a TIN check

Checks whether a US Taxpayer Identification Number (SSN or EIN) and a name match IRS records. The same check can also validate a US mailing address and look up a FATCA GIIN. A check that returns an answer is charged in credits ("Get the price of a TIN check" tells how many); a TIN refused as invalid or an unavailable check costs nothing. In sandbox, checks are free and answered from sample data, and mock lets you choose the answer.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
null or RunTinCheckAddress (object)
giin
string or null

A FATCA Global Intermediary Identification Number, to look up on the IRS list of registered foreign financial institutions.

null or TinCheckMockOptions (object)
name
required
string

A person's full name or a company's legal name, as it appears on IRS records.

tin
required
string

A US Taxpayer Identification Number: the nine digits of an SSN or EIN. Spaces and hyphens are accepted and ignored.

Responses

Request samples

Content type
application/json
{
  • "address": { },
  • "giin": "string",
  • "mock": { },
  • "name": "string",
  • "tin": "string"
}

Response samples

Content type
application/json
{
  • "address": { },
  • "chargedCredits": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdByEmail": "string",
  • "deathMasterFile": "NOT_PROCESSED",
  • "einNameMatch": "NOT_PROCESSED",
  • "einNameMatchData": "string",
  • "giin": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "outcome": "MATCH",
  • "tinMasked": "string",
  • "tinType": { },
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4",
  • "watchlistStatus": "NOT_PROCESSED",
  • "watchlists": [
    ]
}

Get the price of a TIN check

What the next check costs this organization, in credits. Zero in the sandbox.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "credits": 0
}

Get one TIN check

The check with everything it found. 404 when the id is unknown in this organization and environment.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

check_id
required
string <uuid>

TIN check ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "address": { },
  • "chargedCredits": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdByEmail": "string",
  • "deathMasterFile": "NOT_PROCESSED",
  • "einNameMatch": "NOT_PROCESSED",
  • "einNameMatchData": "string",
  • "giin": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "outcome": "MATCH",
  • "tinMasked": "string",
  • "tinType": { },
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4",
  • "watchlistStatus": "NOT_PROCESSED",
  • "watchlists": [
    ]
}

API Keys

Transaction Monitoring

Submit a transaction for monitoring

Records a payment event, checks it against your organization's monitoring rules, and answers right away with the decision (ALLOW, REVIEW or BLOCK), the rules that matched and any alerts raised. Sending the same externalId again returns the first answer without checking or charging the transaction twice, so it is safe to retry. Each new transaction is charged.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
amountMinor
required
integer <int64>

Integer minor units (e.g. cents) — no float money.

channel
string or null

e.g. card, sepa, onchain.

null or TmCounterpartyRequest (object)
currency
required
string

ISO 4217 alpha-3 (letters only, e.g. EUR). Uppercase on the wire; any case accepted.

description
string or null

Payment reference / free-text description (SEPA causale) — the keyword-screening surface.

direction
required
string (TmTransactionDirection)
Enum: "DEPOSIT" "WITHDRAWAL" "TRANSFER"

Direction of a monitored transaction relative to the monitored identity.

externalId
required
string

Client-side transaction id — the idempotency key per organization: replaying the same externalId returns the original result without re-evaluating or double-billing.

externalUserId
string or null

Optional client-side user reference (passthrough).

identityId
required
string <uuid>

The monitored (verified) identity this event belongs to.

metadata
any

Arbitrary client metadata, persisted verbatim for audit/replay.

occurredAt
required
string <date-time>

Client event time. Rejected if more than 24h in the future — a small clock-skew allowance, not an invitation to backdate/forward-date events.

originCountry
string or null

ISO 3166-1 alpha-2 — the monitored identity's side (defaults to the org's operating country semantics; overridable per event for multi-country books).

rail
string or null

Provider/rail (open_banking, sepa, card, …).

referenceDocumentId
string or null <uuid>

Attached invoice/document reference.

Responses

Request samples

Content type
application/json
{
  • "amountMinor": 0,
  • "channel": "string",
  • "counterparty": { },
  • "currency": "EUR",
  • "description": "string",
  • "direction": "DEPOSIT",
  • "externalId": "string",
  • "externalUserId": "string",
  • "identityId": "ebc92baa-b430-498d-b30d-132ff32a5256",
  • "metadata": null,
  • "occurredAt": "2019-08-24T14:15:22Z",
  • "originCountry": "string",
  • "rail": "string",
  • "referenceDocumentId": "62b3ae25-6839-46bc-87a7-4f7c1681cf0b"
}

Response samples

Content type
application/json
{
  • "alerts": [
    ],
  • "decision": "ALLOW",
  • "firedRules": [
    ],
  • "replay": true,
  • "riskProbability": 0.1,
  • "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"
}

Get a monitored transaction

Returns a transaction submitted for monitoring: its payment status, the decision and risk probability, the rules that matched, and any alerts it raised.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

transaction_id
required
string <uuid>

Transaction ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
{
  • "alerts": [
    ],
  • "amountMinor": 0,
  • "channel": "string",
  • "counterpartyAddress": "string",
  • "counterpartyCountry": "string",
  • "counterpartyId": "55bd9d74-f636-4cc8-885a-e78ea532e2ad",
  • "counterpartyName": "string",
  • "currency": "string",
  • "decidedAt": "2019-08-24T14:15:22Z",
  • "decision": { },
  • "description": "string",
  • "direction": "DEPOSIT",
  • "externalId": "string",
  • "externalUserId": "string",
  • "firedRules": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "identityId": "ebc92baa-b430-498d-b30d-132ff32a5256",
  • "ingestedAt": "2019-08-24T14:15:22Z",
  • "occurredAt": "2019-08-24T14:15:22Z",
  • "originCountry": "string",
  • "rail": "string",
  • "referenceDocumentId": "62b3ae25-6839-46bc-87a7-4f7c1681cf0b",
  • "riskProbability": 0,
  • "status": "PENDING"
}

Update a transaction's payment status

Sets the payment status of a monitored transaction: PENDING, SETTLED, FAILED, CANCELED or REVERSED. A transaction that failed, was canceled or was reversed stops counting towards the amount and frequency limits of your rules. Sending the same update again is safe.

Authorizations:
x-api-key
path Parameters
organization_id
required
string <uuid>

Organization ID

transaction_id
required
string <uuid>

Transaction ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Request Body schema: application/json
required
status
required
string (TmTransactionStatus)
Enum: "PENDING" "SETTLED" "FAILED" "CANCELED" "REVERSED"

Payment lifecycle status (client-updatable via PATCH). Velocity counts transactions while Pending/Settled and backs them out on a one-time transition into a terminal-negative state.

Responses

Request samples

Content type
application/json
{
  • "status": "PENDING"
}

Response samples

Content type
application/json
{
  • "alerts": [
    ],
  • "amountMinor": 0,
  • "channel": "string",
  • "counterpartyAddress": "string",
  • "counterpartyCountry": "string",
  • "counterpartyId": "55bd9d74-f636-4cc8-885a-e78ea532e2ad",
  • "counterpartyName": "string",
  • "currency": "string",
  • "decidedAt": "2019-08-24T14:15:22Z",
  • "decision": { },
  • "description": "string",
  • "direction": "DEPOSIT",
  • "externalId": "string",
  • "externalUserId": "string",
  • "firedRules": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "identityId": "ebc92baa-b430-498d-b30d-132ff32a5256",
  • "ingestedAt": "2019-08-24T14:15:22Z",
  • "occurredAt": "2019-08-24T14:15:22Z",
  • "originCountry": "string",
  • "rail": "string",
  • "referenceDocumentId": "62b3ae25-6839-46bc-87a7-4f7c1681cf0b",
  • "riskProbability": 0,
  • "status": "PENDING"
}

Flows

Get full flow details

Returns a flow by its slug, with its steps and their settings, as the verification reads it before it starts. Send zypheAccessSig when the flow only accepts signed links.

path Parameters
slug
required
string

Flow slug

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

zypheAccessSig
string

Signed access token (JWS). Required only when flow signed access is enabled.

Responses

Response samples

Content type
application/json
{
  • "flow": {
    },
  • "flowPartnerOrganizationsNames": [
    ],
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "organizationName": "string",
  • "settings": {
    },
  • "theme": { }
}

Verification Requests

Get a verification request

Returns one of the user's verification requests on a flow: its status, the step it belongs to, and the results recorded so far. Called with the user's session token.

Authorizations:
jwt-auth
path Parameters
flow_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Flow ID

verification_request_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Verification Request ID

query Parameters
sandbox
boolean

Whether to use sandbox mode

Responses

Response samples

Content type
application/json
{
  • "externalId": "string",
  • "identity": {
    },
  • "passkey": { },
  • "verificationRequest": {
    },
  • "wallet": { }
}

Get completed verification requests

Lists the verification requests the user has completed on a flow, one per completed step. Called with the user's session token.

Authorizations:
jwt-auth
path Parameters
flow_id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Flow ID

query Parameters
sandbox
required
boolean
locale
string (Locale)
Enum: "en" "it" "de" "es" "fr" "hi" "id" "pt"

Locale identifier

Responses

Response samples

Content type
application/json
[
  • {
    }
]