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.

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:

1. 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.

2. 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:

1. Call POST /cases/preview with the case payload
2. Check requiredActions for MissingKycVerification
3. If present, surface the solutionUrl to the creditor (e.g., as a banner or redirect)
4. 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.

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