Workflows

Workflows are how most checks are initiated.

We have big plans for workflows in the future including them being customizable and event driven. But for now we only have basic workflows available that run single checks.

Available workflows

Workflow name	Checks initiated
kyc	KYC
fin-vul	Financial vulnerability
aml	AML
bav	BAV

Execute workflow

Executes a workflow on the desired case.

Endpoint	/api/workflows/execute
Method	POST
Content type	application/json

Fields

Property	Required	Max Length	Notes
caseId	✅	integer (int64)	Unique CaseId to run checks for
workflowName	✅		Either 'kyc', 'fin-vul', 'aml' or 'bav' depending on which service you want to run
workflowOptions			Object of key-value string pairs, workflow options listed below
externalReference			Idempotency key as outlined here

WorkflowOptions

Property	Value	Notes
enableOngoingMonitoring	true or false	Currently only available on AML. Sets whether the person should be checked recurringly.
bankAccountId	long	Currently only available for BAV. ID of the bank account to verify. Get the ID via Bank Account Management.

Request

A request requires a case ID and a workflow name. Options depend on the workflow — for example bankAccountId for BAV:

{
    "caseId":"123",
    "workflowName":"bav", 
    "workflowOptions": {
        "bankAccountId": "456"
    }
}

KYC example:

{
    "caseId":"123",
    "workflowName":"kyc", 
    "workflowOptions": { // optional
        "enableOngoingMonitoring": "false" // optional — AML only
    },
    "externalReference": "abc123" // optional
}

Response

Response 200 OK

The check has been started (or, for synchronous checks like AML, completed). See Checks for the response shape of each check type. Most checks run asynchronously — poll the check endpoint or listen for the completion webhook.

Response 400 Bad Request

Returned if the workflow isn't enabled for your client at all (the process is switched off in your EyeDP configuration), or the request itself is malformed.

{
    "errors": [
        "kyc workflow not enabled for case 123"
    ]
}

Response 422 Unprocessable Entity

Returned when the workflow is enabled, but the case doesn't currently hold enough valid information to run it — for example, no date of birth for KYC, or an invalid sort code for BAV. This is different from a 400 because while the request is well-formed, the underlying data isn't valid for the check being attempted. Add or correct the data and re-run the workflow.

Each entry in errors covers one issue. Where an issue is about a specific field, the message is prefixed with that field's name; issues about the case as a whole (no snapshot yet, no person record, etc.) aren't prefixed.

{
    "errors": [
        "sort_code: Sort code must be at least 6 characters."
    ]
}

A request with multiple issues returns one entry per issue:

{
    "errors": [
        "GivenNames: Given name(s) are required for KYC.",
        "DateOfBirth: Date of birth is required for KYC."
    ]
}

Or, when the case is missing something more fundamental than a single field:

{
    "errors": [
        "This case has no snapshot yet."
    ]
}

What's required varies by check — see the case requirements tables on KYC and Financial vulnerability, the Name/DOB/Country requirement noted under AML, and the sort code / account number format rules on Create a bank account for BAV.