Skip to main content

Migrate client data into Passfort

When Passfort's replacing your legacy systems, you should make a plan to migrate your customer data over.

This tutorial will take you through the key elements to plan your migration, including what to include in your migration script, how to test it, and what you'll need to know to perform the migration.

If you have any questions you can contact our Client Service team at

Plan your migration


Consider when the migration needs to be started and completed.

You may want to migrate all existing clients before going live so you can ensure the platform runs successfully alongside your systems.

If you have any third-party contractual deadlines that need to be met, such as existing relationships with data providers that may be expiring, you should factor these into your timeline as well.


To determine the scope of your migration, consider the following:

  • Do you want to migrate all your clients?

    You might want to migrate just those actively using your products.

  • How many clients do you want to migrate?

    If some of your clients are companies, you should include any company associates, like directors and shareholders, in this number. Learn more about company associates.

  • How much client data do you want to add to each Passfort profile?

    The section here, Create the migration script, provides more information.

  • Do you want to put your migrated clients through a full onboarding process?

    You might choose to run limited compliance instead.

Every client you migrate to Passfort will contribute to the number of Active Profiles in your commercial agreement.

Full onboarding versus limited compliance

You can choose to put your migrated clients through your full onboarding process or perform just the key compliance checks.

You might choose full onboarding if, for example, you've experienced a regulation breach or the compliance rules have changed since your clients were first onboarded.

This is the most straightforward migration path because you'll be treating all customers, existing and new, the same. You only need one workflow.

Alternatively, with limited compliance, you can set up ongoing monitoring and only run the most important checks. This option assumes any compliance in your legacy system is enough.

There are two options to process clients with limited compliance:

  • Use a separate product for migrated clients.

    This product would have a compliance flow to initiate any monitoring processes and perform key checks. If you want to apply your normal product to these accounts in the future, you can.

  • Use the main product, but temporarily disable some compliance checks.

    When the migrated clients go through the flow, the checks you don't want to run, such as electronic identity checks, will be disabled. After they're migrated, the checks are turned on again, so new clients go through the full set of checks. With this option, all clients must be migrated to Passfort before any new clients can be added.

If you're using the second option, tasks with autocompletion may need to be resolved manually for the migrated clients. To do this, you can listen to the Manual action required webhook to find out when Passfort's automated processes have ended, then use the API to manually complete the tasks.

Data providers

Before you start your migration, consider which data providers you want to use.

In particular, you should decide which ones you'll use for ongoing monitoring. Data providers with ongoing monitoring continually scan for changes to check results and push any new updates to Passfort. Most commonly, ongoing monitoring is used for the PEPs and sanctions screening check (individuals) and the Sanctions and adverse media screening check (companies).

Other checks, like the Company data check and the Merchant fraud check, offer ongoing monitoring as well. To find out if you can use ongoing monitoring for a data provider in Passfort, see its configuration topic.

If you're changing data providers or you're adding a monitoring service, you'll need to rescreen your migrated clients in order to initiate ongoing monitoring.

If you already have a monitoring service with a data provider and you wish to continue that relationship through Passfort, contact us and we'll help you get set up.

It's not possible for one data provider to take its state from another provider, so to initiate ongoing monitoring on a profile, you'll need to run the check once per provider.

Support and logistics

We'll be here to support you if you have any questions.

To ensure we can quickly troubleshoot any issues with the migration and also continue to provide a stable service for all our customers, we ask that you keep the following in mind:

  • Inform us at least 48 hours before you start migrating clients. Let us know how many records are likely to be migrated.

  • We ask that you migrate clients in chunks, as described in the Perform the migration section.

  • Use a separate API key for your migration. Learn how to issue a new API key.

If you are unable to do any of these tasks, speak to us as soon as possible. You can contact your account manager or message us at

Create the migration script

When you're ready to write your script, you can use the same API as you would for regular onboarding.

Sync profile data with your system data

Once you've created the profiles for the migration, you may need to update your other systems, such as a CRM or account system, with any changes from Passfort.

Use Passfort’s webhooks to receive these updates about when information has changed.

For a full list of webhook events and instructions for setting them up, see About Passfort's webhooks. A description of each webhook body can be found in the webhooks section of the API resources. When you're building your webhook receiver, it's important to consider the response time. See Returning a 200 response for more details.

For step-by-step instructions on how to update your system data when Passfort's profile data changes, see Sync profile data with your system data in the API.

Test the migration

Once you have planned and prepared your migration, you should test your script and webhook receiver before deploying them.

Passfort recommends testing in two phases:

  1. Run a test in your demo environment.

  2. Run a smaller test run in your production environment.

See Testing Passfort for more information about the demo and production environments.

Demo environment test

The test in your demo environment should confirm the following:

  1. Were the profiles and product applications added correctly?

  2. Were files uploaded correctly?

  3. Did the profiles go through the correct compliance checks?

  4. Did the exported data maintain its quality and format?

  5. Did the migration script accurately perform data transformation?

  6. Was the webhook receiver performance stable?

There's no charge for the checks run in the demo environment, so you can perform your test on a reasonable number of profiles. Most clients find 100 profiles is about the right size.

Ideally, the profiles should cover different kinds of clients and data types.

Production environment test

If your demo environment test passes, we recommend performing a smaller-scale test, such as five to ten clients, in your production environment.

This allows you to confirm that any live data providers are in place and configured correctly.

If you're performing limited compliance, it also allows you to confirm that the temporary changes to the workflow are in place.

To prevent duplicate profiles, remove these test cases from your full migration when you run it later. You don't need to give us advance warning before running the small-scale test.

Perform the migration

We ask that you migrate clients in chunks, starting with a small number of clients and then ramping up your throughput.

For example:

  1. Run a single process for the first 500 clients.

  2. Ramp up to three concurrent processes for the next 1000 clients.

  3. Ramp up to five concurrent processes.

Let us know at least 48 hours before each increase in volume.

Expected throughput performance

Passfort imposes concurrency restrictions rather than a limit on the number of profiles you can add per hour.

We suggest no more than five concurrent processes from the system running the migration.

If you're onboarding new clients while you're performing large migrations, your onboarding times may be impacted. Contact your account manager so we can support you and ensure system stability and monitoring during this time.

Expected data provider performance

Some data providers impose their own limits and rates. These may differ between testing and production environments.

Contact your data provider to learn more.

Expected webhook performance

For more information about webhook performance, see Returning a 200 response.

If the webhook status queue becomes stalled, try updating the endpoint.

Additional information