KYC Verification

How director identity verification works for collection partners that require it, and how to handle it in your integration.

What Is KYC Verification?

Some collection partners require basic identity information about a creditor's director before cases can be worked. Whether a partner requires KYC is controlled by a per-partner flag — not all partners require it.

The KYC form collects three fields about a senior manager or director of the creditor company: full name, home address, and date of birth. KYC is completed once per creditor — not per case. Once a creditor submits their KYC data, all future cases for that creditor pass the KYC check regardless of jurisdiction.

Why KYC Exists

KYC exists because some collection partners operate under regulatory regimes that require them to verify the identity of the business they are collecting on behalf of before taking any action on a case. The clearest example today is the United Kingdom: UK collection activity falls under Anti-Money Laundering (AML) obligations, and Debitura's UK partner — Oriel Collections Limited — must hold director-level identity data on file for every creditor whose cases they work.

This is why KYC is partner-scoped rather than jurisdiction-scoped in the API: the requirement is driven by the collection partner's regulatory footprint, not by the debtor's country. In practice, UK cases are routed to Oriel via a jurisdiction carveout, so any creditor submitting UK cases will encounter the KYC requirement.

For you as a referral partner, this means:

You don't decide which cases require KYC — Debitura does, based on which collection partner the case is routed to
KYC is a hard requirement: it cannot be skipped, deferred, or bypassed with allowPendingContracts
Your creditors only need to complete it once, and the data covers every future case routed to that partner

What Your Client Experiences

When a creditor of yours needs to complete KYC, they are directed to a Debitura-hosted form that asks for three pieces of information about a director or senior manager of their company:

Full name
Home address
Date of birth

After submitting, they are redirected back to the returnUrl you configured and their case submission can proceed. There is no back-and-forth with the collection partner and no document upload — the form is short by design, and the data is stored once against the creditor.

Two moments in the integration can trigger this experience:

During onboarding — if their first case is routed to a KYC-required partner, the KYC step is inserted into the onboarding sequence before contract signing. They complete it as part of the same hosted flow that handles SDCA and PoA.
On a later case submission — if they onboarded without KYC (for example, their first case was non-UK) and they later submit a case routed to a KYC-required partner, your integration receives a 422 MissingKycVerification and must surface the solutionUrl to them.

Both paths end at the same Debitura-hosted form. The difference is only whether your integration has to react to a 422 or whether the onboarding URL handles it transparently.

When KYC Is Enforced

KYC verification is enforced only in referral partner flows. Specifically, it applies when cases are submitted via the Customer API using a bearer token minted through the referral partner authentication flow. Direct API key callers (XApiKey) are not affected.

This means:

Cases submitted via bearer token to a partner with KYC enabled — KYC is checked
Cases submitted via XApiKey to the same partner — KYC is not checked
Cases submitted through the Debitura portal — KYC is not checked

During Onboarding

When a creditor onboards through your referral partner flow and the resolved collection partner requires KYC, a verification step is automatically inserted into the onboarding sequence — between the Users & Roles step and the contract signing step. If the partner does not require KYC (or KYC is already on file), this step is skipped automatically.

No integration work is needed for this scenario. The onboarding URL returned by POST /clients handles everything — SDCA, PoA, and KYC — in a single flow.

After Onboarding — First Case in a KYC Jurisdiction

When an existing creditor submits a case routed to a partner that requires KYC, and the creditor has not yet completed KYC verification, the API returns 422 Unprocessable Entity:

{
  "businessErrors": [
    {
      "type": "MissingKycVerification",
      "message": "KYC verification is required before cases can be submitted to this collection partner.",
      "solutionUrl": "https://..."
    }
  ]
}

This happens in two scenarios:

Client onboarded before the KYC feature existed — they never went through KYC during onboarding. On their next case submission to a KYC-required partner, they get the 422. They complete it once and all future cases go through.
Client onboarded with a non-UK case — their initial onboarding did not include the KYC step because the resolved partner did not require it. When they later submit a UK case, they get the 422.

The solutionUrl points to a Debitura-hosted form where the creditor fills in the three fields and submits. After completion, retry the case submission — it proceeds without error.

Interaction with allowPendingContracts

Unlike contract requirements (SDCA, PoA), allowPendingContracts: true does not skip the KYC check. KYC is always a hard 422 block. There is no pending state for KYC — the creditor must complete it before the case can be created.

Checking KYC Status Before Submission

Use POST /cases/preview to check KYC requirements before creating a case. The response includes:

Field	Type	Description
`requiresKycVerification`	boolean	Whether the resolved partner requires KYC
`hasKycOnFile`	boolean	Whether the creditor has already completed KYC

If KYC is missing, the requiredActions array includes a MissingKycVerification entry with a solutionUrl:

{
  "type": "MissingKycVerification",
  "message": "KYC verification is required before cases can be submitted to this collection partner.",
  "solutionUrl": "https://...",
  "isBlocking": true
}

This follows the same requiredActions shape as MissingDebtCollectionContract and MissingPowerOfAttorney. If you already parse requiredActions for contract requirements, KYC works the same way.

Recommended Flow

Rather than waiting for a 422 on POST /cases, check upfront:

Call POST /cases/preview with the case payload
Check requiredActions for MissingKycVerification
If present, surface the solutionUrl to the creditor (e.g., as a banner or redirect)
Once completed, submit the case via POST /cases — it goes through without the KYC block

This avoids the problem of handling an intermediate state where the case submission failed but KYC needs to be completed before retrying.

Manual KYC Submission via API

If a creditor completed KYC outside the automated flow (e.g. manually with the collection partner), you can submit their KYC data directly via the Referral Partner API. This records the verification in the system so the creditor is not prompted again.

Client List — KYC Status

GET /clients includes KYC fields on each client:

Field	Type	Description
`requiresKycVerification`	boolean	Whether this client has cases at a partner that requires KYC
`kycVerification`	object \| null	The latest KYC record, or `null` if none on file

When kycVerification is present, it contains:

{
  "directorFullName": "James Wilson",
  "directorHomeAddress": "45 High Street, London, SW1A 2AA",
  "directorDateOfBirth": "1975-08-22",
  "dateCreated": "2025-01-15T10:30:00Z"
}

Submitting KYC Data

POST /clients/{externalTenantId}/kyc-verification

Submit director verification data for a client:

{
  "directorFullName": "James Wilson",
  "directorHomeAddress": "45 High Street, London, SW1A 2AA",
  "directorDateOfBirth": "1975-08-22"
}

Response: 201 Created with the saved KYC record (same shape as above, with dateCreated).

Error responses:

Status	Meaning
400	Validation error — missing or invalid fields
404	No active client found for the given `externalTenantId`

Multiple submissions are allowed — the latest record is always used for verification checks. This means you can correct previously submitted data by submitting again.

Integration Checklist

Before going live with a KYC-required jurisdiction, verify:

422 handling is in place — your integration catches MissingKycVerification and surfaces the solutionUrl to the creditor
Preview check implemented — use POST /cases/preview to detect KYC requirements before submission
Return URL configured — your returnUrl brings the creditor back to a sensible location after completing KYC
Retry logic implemented — after the creditor completes KYC and returns, the case submission is retried
Test environment validated — run the full flow: submit a case to a KYC-required partner → get the 422 → complete KYC → retry → confirm the case is created
Manual KYC submission tested (if applicable) — use POST /clients/{externalTenantId}/kyc-verification to submit KYC for an existing client, then verify the client list shows kycVerification populated

What Is KYC Verification?​

Why KYC Exists​

What Your Client Experiences​

When KYC Is Enforced​

During Onboarding​

After Onboarding — First Case in a KYC Jurisdiction​

Interaction with allowPendingContracts​

Checking KYC Status Before Submission​

Recommended Flow​

Manual KYC Submission via API​

Client List — KYC Status​

Submitting KYC Data​

Integration Checklist​