Skip to main content

Using Passfort

Migrating client data into Passfort

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

This article 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 us at, we'll be happy to help.

Planning 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 on Creating 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 Deployment process 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

Creating the migration script

When you're ready to write your script, you can use the same API as you would for regular onboarding. All documentation and support materials are available at

Script example

How you build the script is up to you, but it might look something like this:

Create a profile and product application

Call the following API endpoint to create a profile and add an application:

For step-by-step instructions for using the API endpoint, see Create profiles.

The script should also create profiles for any company associates you're onboarding, such as directors, shareholders, and so on. Profiles for company associates need additional API calls to create a link between them and the parent company profile. To learn how to do this, see Create a profile for an associate and link it to a company.

We recommend only migrating the profile data required to perform your compliance processes.

At a minimum, include the following information for individual profiles:

  • The individual's full name and, optionally, title.

  • collected_data.personal_details.dob: The individual's date of birth.

  • collected_data.address_history.address: The individual's address. If you're running an Electronic identity check or you want to do a KYC refresh, the full address is required. If not, only the country is required.

  • collected_data.customer_ref: The unique reference from your export system, used to help you track the profile in Passfort.

At a minimum, include the following information for company profiles:

  • The company's name.

  • collected_data.metadata.number: The company's registration number.

  • collected_data.metadata.country_of_incorporation: The country in which the company is incorporated.

  • collected_data.customer_reference: The unique reference from your export system, used to help you track the profile in Passfort.

You may need to provide additional data depending on:

  • What information your data providers require to run their checks. To find out more, see the configuration information for your data providers.

  • Whether your risk models use specific profile data. Note that this only applies to customers using Passfort's optional Risk module.

  • Whether your compliance teams need any additional data to complete their manual workflows.

To see which data providers are configured on your account, log into the Passfort portal and go to Policy Builder > Data providers. To see which risk factors are used in your risk models, go to Policy Builder > Risk management. If you have not yet chosen your data providers or if you're using the Risk module and you have not yet chosen your risk models, contact us and we'll help.

Add audit records or additional documentation

You can upload any additional audit records or other documentation to the profile. These are added as files.

Use this endpoint to add files to a profile:{profile_id}~1files/post

Any file uploads must be in one of Passfort’s supported file types, which are PDF, JPEG, PNG, or GIF, and encoded in Base64. For step-by-step instructions for using the API endpoint, see What are files, documents, and document_images in the API?.

Add a tag to the profile

Tags are used to attach a label to a profile. We suggest adding a migrated tag to help you track which profiles were moved over from your legacy system.

Use this endpoint to add tags to a profile:{profile_id}~1files/post

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

Setting up webhooks

For a full list of webhook events and instructions for setting them up, see Configuring 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.

Updating your system data

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.

Performing the migration


Before deploying your script and webhook receiver, you should test 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:

  1. Were the profiles and 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 - 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.

Deployment process

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. Passfort undergoes regular performance testing, as outlined in the System Architecture guide available at

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.