Replacing a KYC provider is not just an API swap. This runbook helps product, compliance, and engineering teams plan an identity verification vendor migration, compare old and new decisions, protect historical records, and monitor onboarding continuity before, during, and after cutover.
Overview
A KYC platform migration can affect every part of customer onboarding: document collection, biometric checks, sanctions screening, manual review, case management, decisioning, reporting, and retention. The safest approach is to treat the change as a controlled risk and data migration rather than a simple integration project.
Start by defining what must remain stable. Typical continuity requirements include the customer journey, required evidence, approval and rejection logic, review escalation, audit trails, reporting fields, and access controls. Then identify what may intentionally change, such as supported countries, document types, liveness options, fraud signals, review tooling, or webhook behavior.
Do not assume that two providers use equivalent labels. An “approved” result may represent different checks, thresholds, or review paths. During the migration, preserve the original provider’s raw response and your normalized internal decision separately. This distinction supports investigations, regulator or auditor requests, customer support, and later model or rule analysis.
Use a written migration owner and a decision log. The owner coordinates product, engineering, compliance, security, privacy, fraud, operations, and support. The decision log records assumptions, unresolved gaps, approval criteria, rollback authority, and the evidence used to move between stages.
What to track
1. Build a requirements matrix
Before selecting an implementation path, compare the existing and replacement identity verification software against requirements that can be tested. A useful matrix includes:
| Area | Questions to answer | Evidence to retain |
|---|---|---|
| Coverage | Which countries, regions, customer types, documents, languages, and channels are supported? | Provider capability responses, test results, and known exclusions |
| Verification | Does the workflow support document checks, face comparison, liveness, address evidence, and manual review where required? | Test cases, response fields, and fallback behavior |
| Decisioning | Which results are approved, rejected, pending, or routed to review? | Decision map and rule version |
| Integration | How are sessions created, results delivered, retries handled, and errors reported? | API contract, webhook examples, and failure tests |
| Privacy and security | What personal data is collected, where is it processed, how is it retained, and who can access it? | Data-flow diagram, contract terms, and access review |
| Operations | Can reviewers investigate cases, correct errors, and export required evidence? | Queue tests, audit events, and operating procedures |
| Commercial fit | How do volume tiers, retries, manual reviews, storage, and optional checks affect total cost? | Documented assumptions and scenario estimates |
Recheck this matrix when target markets, customer segments, or regulatory interpretations change. Provider documentation can also change independently of your application, so capability claims should be verified through current testing rather than copied from an earlier evaluation.
2. Map data and decisions before mapping endpoints
Create a field-level mapping between the old and new systems. Include customer identifiers, verification session IDs, document types, country codes, timestamps, check outcomes, reason codes, review status, consent or notice records, and webhook event IDs. Mark each field as equivalent, transformable, unavailable, or newly introduced.
A simple mapping template can use these columns:
- Internal field: the canonical field used by your platform.
- Source field: the old provider’s field and format.
- Target field: the replacement provider’s field and format.
- Transformation: normalization, code conversion, truncation, or no change.
- Requiredness: required, optional, conditional, or not collected.
- Evidence and owner: test case, decision owner, and date verified.
Keep a decision mapping alongside the data mapping. For example, document “pass,” “fail,” “pending,” and “review” may not align one-to-one. Define how each target outcome becomes an internal state, what happens when a new outcome appears, and whether an existing customer can be rechecked without starting a duplicate case.
3. Decide what happens to historical records
Most migrations should not begin by moving every historical image or identity document into the new provider. First classify records by purpose and retention need. Some records may need to remain in the original environment for auditability, while your application stores only a provider reference, normalized result, timestamps, and a controlled link to evidence.
For each record category, document whether it will be retained in place, exported, transformed, reverified, or deleted according to your approved retention process. Preserve chain-of-custody information: who performed the check, which provider and workflow version were used, when the result was received, and whether a human changed the decision. Avoid using a migration as a reason to collect data that the new workflow does not require.
4. Use a parallel-run workflow
A parallel run compares providers without making the new result the sole production decision immediately. Define a controlled sample or routing method that is appropriate for your risk model and privacy obligations. Where lawful and necessary, run equivalent test cases using synthetic, consented, or otherwise authorized data; do not duplicate sensitive identity evidence casually.
- Send the same eligible scenario through the agreed comparison path.
- Normalize both responses into a common internal schema.
- Compare final decisions, individual checks, reason codes, latency, errors, and review outcomes.
- Investigate material disagreements by region, document type, device, language, and customer journey step.
- Record whether the difference comes from provider capability, configuration, data quality, thresholding, or an internal mapping defect.
Set exit criteria before the test begins. These may include acceptable disagreement rates by segment, no unresolved critical security issue, stable webhook processing, trained review staff, and a documented response to unsupported documents or provider outages. Avoid relying on a single aggregate approval rate, which can hide serious regional or segment-level changes.
Cadence and checkpoints
A migration benefits from checkpoints rather than one large launch decision. Use the following sequence as a practical operating rhythm.
| Checkpoint | Primary work | Required decision |
|---|---|---|
| Discovery | Inventory workflows, data, contracts, dependencies, and market requirements. | Is the replacement provider capable of supporting the intended scope? |
| Design | Approve data mapping, decision mapping, privacy controls, fallback paths, and ownership. | Can the target design be operated and audited? |
| Build | Implement adapters, normalized schemas, idempotency, logging, feature flags, and alerts. | Does the integration fail safely and remain observable? |
| Validation | Run functional, security, accessibility, regional, document, and webhook tests. | Are critical defects closed or explicitly accepted? |
| Parallel run | Compare decisions and operational outcomes across defined segments. | Does evidence support a controlled cutover? |
| Phased cutover | Route a limited segment, monitor, and expand only after review. | Are customer and risk indicators within agreed limits? |
| Stabilization | Reconcile records, close temporary routes, update procedures, and review incidents. | Is the new workflow the dependable system of record for new cases? |
During the first days and weeks after cutover, review metrics at least daily if volume permits. After stabilization, move to a weekly operational review and a monthly or quarterly vendor review. The right cadence depends on volume, risk, geography, and change frequency; document the reasoning rather than adopting an arbitrary schedule.
How to interpret changes
Track the migration as a segmented dashboard, not a single success score. At minimum, monitor:
- Approval rate: compare by country, document type, channel, and customer segment.
- Manual-review rate: separate provider routing from your own operational rules.
- Fraud losses or confirmed suspicious cases: interpret with investigation lag in mind.
- Latency: measure both provider response time and total customer journey time.
- Technical reliability: track timeouts, rejected requests, duplicate webhooks, parsing errors, and retry volume.
- Regional performance: identify markets where document coverage, language, or device behavior changes outcomes.
- Customer support signals: monitor abandonment, repeated attempts, complaints, and requests for manual assistance.
- Audit completeness: confirm that every decision has the required event, reason, timestamp, and actor information.
A rise in approvals is not automatically an improvement, and a rise in reviews is not automatically a provider failure. Check whether traffic mix, policy thresholds, document availability, fraud pressure, or a new customer flow changed at the same time. Use cohort comparisons and hold a consistent baseline where possible.
For false positives, inspect the review queue by reason and segment before changing a threshold. For false negatives or increased fraud, examine the individual checks, evidence quality, and downstream investigation results. Teams working with face verification or liveness should validate those components separately; the liveness detection testing checklist provides a focused testing reference. For review-queue tuning, see the false-positive triage playbook.
Maintain a rollback plan that can be executed without deleting evidence. Use feature flags or routing controls, define who can authorize rollback, preserve in-flight session handling, and specify how customer support will explain interrupted or repeated verification. Rollback should restore a known working path, not merely switch an endpoint.
When to revisit
Revisit this runbook on a monthly or quarterly cadence during normal operations, and immediately after a material change. Triggers include a new country or document type, a product launch, an API or SDK deprecation, a contract renewal, a provider outage, a significant fraud event, a privacy or security review, or a sustained change in approval, review, latency, or regional performance.
At each review, refresh the requirements matrix, confirm supported capabilities, verify data-processing and retention assumptions with the appropriate internal owners, and sample recent decisions. Review pricing and contract assumptions separately from technical performance; volume, retries, manual handling, and optional checks can alter the business case without changing the API.
Keep a short migration record that includes the current provider configuration, workflow version, known limitations, rollback procedure, dashboard links, and named owners. Before closing the project, schedule the first post-cutover review and preserve the old provider’s records according to the approved retention plan.
Practical next step: create the requirements matrix and field-level mapping first. Then select a small, representative parallel-run cohort, agree on measurable exit criteria, and do not expand routing until product, compliance, engineering, fraud, and operations have reviewed the same evidence.
