Custom Verification Workflows

Custom verification workflows let you assemble your own KYC or KYB verification level out of individual modules instead of picking one of the predefined levels. A workflow you create becomes a level key you can pass to the verification endpoints like any other level.

Custom workflows are enabled per account and separately for KYC and KYB. When they are not enabled, every endpoint in this section returns 403 with Custom verification workflows are not enabled for this client. Contact support to have them switched on.

Modules

A workflow is one base module plus any extra modules you select. The base module is always included and cannot be removed.

Kind	Module key	What it adds
KYC	`id_verification`	Government ID capture and data extraction. Base module, always included.
KYC	`nfc_chip_read`	Reads the chip in an ePassport or eID for tamper-evident data.
KYC	`liveness`	Confirms a live person is present rather than a photo or replay.
KYC	`face_match`	Matches the selfie against the portrait on the ID.
KYC	`proof_of_address`	Collects and checks an address document.
KYC	`proof_of_income`	Questionnaire plus supporting documents for income.
KYC	`source_of_funds`	Questionnaire plus supporting documents for source of funds.
KYC	`aml_screening`	Sanctions, PEP, and adverse media screening.
KYB	`registry_check`	Company registry lookup. Base module, always included.
KYB	`company_documents`	Collects and checks incorporation and ownership documents.
KYB	`key_people`	Identifies directors and beneficial owners.
KYB	`company_aml`	Sanctions, PEP, and adverse media screening for the company.

Call List Modules for the modules actually available to your account, their per-verification prices, and the minimum price floor. Execution order is fixed by UrbanPayX; the order you send modules in is ignored.

Creating a workflow

Create Custom Level takes a display name and the module keys you want:

curl -X POST https://api-sandbox.urbanpayx.com/api/v1/kyc/custom-levels \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Onboarding - full",
    "modules": ["liveness", "face_match", "aml_screening"]
  }'

The response carries:

Field	Meaning
`key`	The level key to pass as `kyc_level` (or `kyb_level`) when starting a verification.
`unit_price_eur`	Per-verification price, frozen at creation time.
`floor_applied`	`true` when the selected modules priced below the minimum and the floor price was used instead.
`version`	Workflow version, starting at 1.
`modules`	The modules stored on the workflow, base module included.

Keys look like cw-1a2b3c4d5e-v1. Your custom levels also appear in List KYC Levels and List KYB Levels next to the predefined ones, so an integration that reads the level list needs no changes.

Editing and deleting

Replace Custom Level takes the same body as create and supersedes the workflow with a new version. The version number increments and the key changes (...-v1 becomes ...-v2), so always store the key returned by the call. The price is re-frozen against current prices. Verification links already issued against the previous version keep working.

Delete Custom Level deactivates the workflow. It stops appearing in the level list and cannot be used for new verifications; links already issued keep working.

Each account has a cap on active custom workflows. Creating one past the cap returns 409 with the limit in the message; delete one or contact support to raise it.

Errors

HTTP status	When it happens
`403 Forbidden`	Custom workflows are not enabled for the account, the caller's role is not permitted, or workflow creation is not enabled for the account in the sandbox environment.
`404 Not Found`	The workflow key does not exist, is not owned by your account, or is already deleted.
`409 Conflict`	The active custom workflow cap has been reached.
`422 Unprocessable Entity`	An unknown or unavailable module key, or a module combination that cannot be sold.
`503 Service Unavailable`	The verification service was temporarily unreachable while provisioning the workflow. Retry.

Permissions

Operation	Permission	Allowed roles
List modules, list workflows	`verification.custom_workflows.read`	`OWNER`, `OPERATIONS`, `DEVELOPER`
Create, replace, delete	`verification.custom_workflows.write`	`OWNER`, `OPERATIONS`

Related guides

KYC Verification - the KYC endpoints a custom level plugs into
KYB Verification - the KYB equivalent