Bank Migration Guide

When a FinTech migrates from one sponsor bank to another on the Synctera platform, resources such as customers, accounts, and external accounts must be recreated under the new bank’s tenant. The Migration Mapping API provides a persistent record of the relationship between an old resource and its newly created counterpart, bridging the two tenants throughout the migration and afterward. Migration mappings do not move data or trigger any automated migration process. They serve two key purposes:

Operational continuity — FinTech operators, Synctera support teams, and bank partners can navigate between old and new records in the Synctera dashboard during and after a migration.
Behind-the-scenes integrations — Synctera uses mappings internally to coordinate activities that require knowledge of both the old and new resource, such as transferring a credit-reporting tradeline from the old bank to the new one without disrupting the customer’s credit history.

Prerequisites

Before using the Migration Mapping API you should be familiar with:

Create a Personal Customer
Create a Business Customer
Accounts — creating deposit and other account types

You will need:

An API key for your existing (old) tenant
An API key for your new tenant
The resource IDs of records you intend to migrate (customers, accounts, etc.)

The migration mapping object

A migration mapping represents the link between one specific resource on the old tenant and its newly created equivalent on the new tenant.

{
  "id": "191edb33-3fca-4c68-8ca5-871fa0d5e3f5",
  "tenant": "456",
  "resource_id": "def45678-0000-0000-0000-000000000002",
  "old_tenant": "123",
  "old_resource_id": "abc12345-0000-0000-0000-000000000001",
  "resource_type": "PERSON",
  "creation_time": "2026-03-01T10:00:00Z",
  "last_updated_time": "2026-03-01T10:00:00Z"
}

Field	Description
`id`	Unique identifier for the migration mapping
`tenant`	Tenant ID of the new bank
`resource_id`	ID of the resource in the new tenant
`old_tenant`	Tenant ID of the old bank
`old_resource_id`	ID of the resource in the old tenant
`resource_type`	The type of resource being mapped. One of `PERSON`, `BUSINESS`, or `ACCOUNT`
`creation_time`	ISO 8601 timestamp when this mapping was created
`last_updated_time`	ISO 8601 timestamp when this mapping was last updated

Cross-tenant access

Migration mappings are stored under the new tenant (tenant) but are queryable using an API key from either the old or the new tenant. This allows operators to look up a mapping regardless of which API key they have at hand during the migration process.

Permissions

Querying and managing migration mappings uses the same permissions as the underlying resource type:

`resource_type`	Required permission
`PERSON`	`customer:read` / `customer:write`
`BUSINESS`	`customer:read` / `customer:write`
`ACCOUNT`	`account:read` / `account:write`

Example: Migrate customers and accounts to a new bank

The following example walks through the complete workflow for migrating personal customers and their associated accounts from an old tenant to a new tenant.

Fetch customers from the old tenant

Start by retrieving the list of customers to be migrated from your existing tenant. In this example, the old tenant ID is 123 and the new tenant ID is 456.

curl -X GET https://api.synctera.com/v2/persons \
  -H "Authorization: Bearer $old_apikey"

The response returns a paginated list of person objects. Record the id of each person you intend to migrate.

{
  "persons": [
    {
      "id": "abc12345-0000-0000-0000-000000000001",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com"
    }
  ],
  "next_page_token": "..."
}

Fetch accounts for each customer

For each customer, retrieve their accounts so you have the full picture of what needs to be recreated.

curl -X GET "https://api.synctera.com/v2/accounts?customer_id=abc12345-0000-0000-0000-000000000001" \
  -H "Authorization: Bearer $old_apikey"

Record the id of each account alongside its owner’s person ID.

Recreate customers on the new tenant

Using the information collected above, create each customer on the new tenant. Submit the same personal information as was on record under the old tenant.

curl -X POST https://api.synctera.com/v2/persons \
  -H "Authorization: Bearer $new_apikey" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "first_name": "Jane",
    "last_name": "Smith",
    "dob": "1985-06-15",
    "email": "jane.smith@example.com",
    "phone_number": "+14155551234",
    "legal_address": {
      "street_line_1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country_code": "US"
    }
  }'

The response includes the new id for the person on the new tenant. Record this value — you will need it when creating the migration mapping.

{
  "id": "def45678-0000-0000-0000-000000000002",
  "first_name": "Jane",
  "last_name": "Smith"
}

Repeat this step for each customer in your migration list, keeping a record of the mapping from old IDs to new IDs.

Recreate accounts on the new tenant

With the new customer IDs in hand, create corresponding accounts on the new tenant. Use the same account configuration (product type, etc.) as the original.

curl -X POST https://api.synctera.com/v2/accounts \
  -H "Authorization: Bearer $new_apikey" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "account_type": "CHECKING",
    "customer_ids": ["def45678-0000-0000-0000-000000000002"]
  }'

Record the new account id returned in the response alongside the old account id.

Create migration mappings for customers

Now that each customer exists on both tenants, create a migration mapping for each person. This call can be made with either the old or the new API key.

curl -X POST https://api.synctera.com/v2/migration_mappings \
  -H "Authorization: Bearer $new_apikey" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "tenant": "456",
    "resource_id": "def45678-0000-0000-0000-000000000002",
    "old_tenant": "123",
    "old_resource_id": "abc12345-0000-0000-0000-000000000001",
    "resource_type": "PERSON"
  }'

A successful response returns the complete migration mapping object:

{
  "id": "191edb33-3fca-4c68-8ca5-871fa0d5e3f5",
  "tenant": "456",
  "resource_id": "def45678-0000-0000-0000-000000000002",
  "old_tenant": "123",
  "old_resource_id": "abc12345-0000-0000-0000-000000000001",
  "resource_type": "PERSON",
  "creation_time": "2026-03-01T10:00:00Z",
  "last_updated_time": "2026-03-01T10:00:00Z"
}

Repeat this step for each migrated customer.

Create migration mappings for accounts

Create a corresponding mapping for each account, linking the old account ID to the new account ID.

curl -X POST https://api.synctera.com/v2/migration_mappings \
  -H "Authorization: Bearer $new_apikey" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "tenant": "456",
    "resource_id": "acct9999-0000-0000-0000-000000000004",
    "old_tenant": "123",
    "old_resource_id": "acct1111-0000-0000-0000-000000000003",
    "resource_type": "ACCOUNT"
  }'

You have now recreated your customers and accounts on the new tenant and established a persistent record linking each pair of old and new resources. Synctera will use these mappings to automatically coordinate any downstream processes that require knowledge of both records, such as transferring credit-reporting tradelines.

Querying migration mappings

You can look up migration mappings at any time using any combination of the following filters.

Look up by resource ID

The resource_id filter matches against both resource_id and old_resource_id. Use it whenever you have an ID and don’t need to constrain which side of the mapping it belongs to — this is the most common lookup pattern.

curl -X GET "https://api.synctera.com/v2/migration_mappings?resource_type=PERSON&resource_id=def45678-0000-0000-0000-000000000002" \
  -H "Authorization: Bearer $new_apikey"

Look up strictly by the old resource ID

If you specifically want to match only on the old side of the mapping (for example, to find every record that originated from a particular old resource), use old_resource_id.

curl -X GET "https://api.synctera.com/v2/migration_mappings?resource_type=PERSON&old_resource_id=abc12345-0000-0000-0000-000000000001" \
  -H "Authorization: Bearer $old_apikey"

Updating and deleting mappings

Update a mapping

Use PATCH to update mutable fields on an existing mapping (for example, if a resource ID was recorded incorrectly).

curl -X PATCH https://api.synctera.com/v2/migration_mappings/191edb33-3fca-4c68-8ca5-871fa0d5e3f5 \
  -H "Authorization: Bearer $new_apikey" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "resource_id": "def99999-0000-0000-0000-000000000002"
  }'

Delete a mapping

curl -X DELETE https://api.synctera.com/v2/migration_mappings/191edb33-3fca-4c68-8ca5-871fa0d5e3f5 \
  -H "Authorization: Bearer $new_apikey"

Deleting a migration mapping removes the link between the old and new resource. Synctera will no longer be able to automatically coordinate downstream processes (such as credit-reporting tradeline transfers) for the affected resource. Only delete a mapping if you are certain the association is no longer needed.

Webhooks

Synctera publishes webhook events for migration mapping lifecycle changes. Subscribe to these events to trigger your own automation during a migration.

Event	Description
`RESOURCE_MAPPING.CREATED`	A new migration mapping was created
`RESOURCE_MAPPING.UPDATED`	An existing mapping was updated
`RESOURCE_MAPPING.DELETED`	A mapping was deleted

See the Webhooks guide for instructions on configuring webhook subscriptions.

API reference

See the full Migration Mappings API reference for request/response schemas and all available parameters:

Navigating migrated resources in the dashboard

Once migration mappings exist, the Synctera dashboard surfaces links between old and new records. On any customer or account detail page, an action menu item — View Migrated Resource — will appear when a mapping exists. Selecting it navigates directly to the corresponding record on the other tenant, making it easy for FinTech operators, bank partners, and Synctera support to trace a resource through the migration.

What happens after mappings are created

After you create migration mappings for your customers and accounts, Synctera uses the mappings to handle certain processes automatically on your behalf. You do not need to take additional action for these:

Credit-reporting tradeline transfer — For FinTechs that report to credit bureaus, Synctera will record a sale of the tradeline on the old bank and a corresponding purchase on the new bank, ensuring your customers’ credit histories remain uninterrupted.

Other post-migration steps — such as re-running KYC, issuing new cards, and migrating balances — must be completed by your team as part of your broader migration runbook. Work with your Synctera implementation manager for a full migration checklist.

​Prerequisites

​The migration mapping object

​Cross-tenant access

​Permissions

​Example: Migrate customers and accounts to a new bank

​Querying migration mappings

​Look up by resource ID

​Look up strictly by the old resource ID

​Updating and deleting mappings

​Update a mapping

​Delete a mapping

​Webhooks

​API reference

​Navigating migrated resources in the dashboard

​What happens after mappings are created

Prerequisites

The migration mapping object

Cross-tenant access

Permissions

Example: Migrate customers and accounts to a new bank

Querying migration mappings

Look up by resource ID

Look up strictly by the old resource ID

Updating and deleting mappings

Update a mapping

Delete a mapping

Webhooks

API reference

Navigating migrated resources in the dashboard

What happens after mappings are created