Skip to main content

zyphe-sdk (1.9.1)

Download OpenAPI specification:Download

License:

SDK: Verification Requests

Create a verification request

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.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "email": "string",
  • "flowSlug": "string",
  • "flowStepSlug": "string",
  • "isSandbox": true,
  • "verificationRequest": {
    },
  • "zid": "string",
  • "zypheAccessSig": "string",
  • "zypheToken": "string"
}

Get the next verification step

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.

credentialType
string or null
Enum: "PASSWORD" "MAGIC_LINK" "PASSKEY" "BOT_TOKEN" "WALLET" "EXTERNAL_ID"

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

chain
string or null
Enum: "ETHEREUM" "ETHEREUM_TESTNET" "SOLANA" "SOLANA_TESTNET"

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": {
    }
}

Submits identity document images for document 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 or null

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)

Images to process (base64-encoded, provider-agnostic format). Either images OR (session_token + interview_id) must be provided, not both.

interviewId
string or null

Interview/session ID for session-based providers (e.g. Incode). If provided along with session_token, the backend will fetch results from the provider.

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

Session token for session-based providers (e.g. Incode JWT). If provided along with interview_id, the backend will fetch results from the provider.

Responses

Request samples

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

Response samples

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

Retrieves the liveness challenge configuration for the current verification request. Use the returned data to present the liveness capture UI 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 or null

Use sandbox environment

Responses

Response samples

Content type
application/json
No sample

Submits liveness capture data (selfie or video) for processing. Call this after completing the liveness challenge from `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 or null

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"
}

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 or null

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

Authorizations:
None
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
}

SDK: KYB

Send a UBO KYC reminder

Sends (or re-sends) the KYC invitation email to a specific UBO on a KYB case, identified by their position in uboDefinitions. Use this to drive UBO outreach on demand — for example when automatic UBO KYC emails are disabled for the flow.

Authorizations:
None
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

KYB result ID

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

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

Authorizations:
None
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
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",
  • "businessInformation": {
    },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": {
    },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": "CLIENT",
  • "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

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

Authorizations:
None
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

KYB result ID

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",
  • "businessInformation": {
    },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": {
    },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": "CLIENT",
  • "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

Adds one or more directors to an existing KYB case and returns the updated KYB result.

Authorizations:
None
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
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",
  • "businessInformation": {
    },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": {
    },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": "CLIENT",
  • "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

Removes a director from a KYB case by their stable id and returns the updated KYB result.

Authorizations:
None
path Parameters
organization_id
required
string <uuid>

Organization ID

kyb_result_id
required
string <uuid>

KYB result ID

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",
  • "businessInformation": {
    },
  • "businessInformationVerification": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "directorDefinitions": [
    ],
  • "documentUploads": [
    ],
  • "effectiveRequiredDocuments": [
    ],
  • "flowStep": {
    },
  • "flowStepId": "10a85e41-8dfe-4c2c-b207-278e137391eb",
  • "fundedAt": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata": { },
  • "nextAction": "CLIENT",
  • "pepAndSanctionsStatus": "REVIEW",
  • "reason": "string",
  • "report": "string",
  • "status": "ACQUIRING",
  • "uboDefinitions": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "verificationRequestId": "21948c97-1944-4395-87f4-b00ba0261bd4"
}

Request a KYB document

Requests an additional document from the business on a KYB case and returns the created document request.

Authorizations:
None
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
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": "string",
  • "status": "PENDING",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "uploadedFilename": "string",
  • "uploadedS3Key": "string"
}

SDK: AML

Run a live AML screening and return the raw provider matches

Queries the configured screening provider (OpenSanctions/Yente or WorldCheck) and returns its raw FollowTheMoney-shaped entity matches — no risk scoring, no persistence. This is the "Stage A only" slice of the on-demand AML flow. Billed per call via pay-as-you-go.

Authorizations:
None
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)

Every meaningful OpenSanctions/Yente search field as an optional string. Result-only fields (sanctions, topics, position occupancies) are not exposed as inputs.

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"
}

API Keys

Flows

Get full flow details

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 or null

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

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 or null

Whether to use sandbox mode

Responses

Response samples

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

Get completed verification requests

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
[
  • {
    }
]