Skip to main content
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: 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"
}
FieldDescription
idUnique identifier for the migration mapping
tenantTenant ID of the new bank
resource_idID of the resource in the new tenant
old_tenantTenant ID of the old bank
old_resource_idID of the resource in the old tenant
resource_typeThe type of resource being mapped. One of PERSON, BUSINESS, or ACCOUNT
creation_timeISO 8601 timestamp when this mapping was created
last_updated_timeISO 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_typeRequired permission
PERSONcustomer:read / customer:write
BUSINESScustomer:read / customer:write
ACCOUNTaccount: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.
1

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/v0/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": "..."
}
2

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/v0/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.
3

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/v0/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.
4

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/v0/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.
5

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/v0/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.
6

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/v0/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 new resource

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

​
Look up by old resource

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

​
Look up using either ID (convenience filter)

If you are not sure whether a given ID is old or new, use the any_resource_id filter. Synctera will check both resource_id and old_resource_id and return any matching mapping. 
curl -X GET "https://api.synctera.com/v0/migration_mappings?any_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/v0/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/v0/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.
EventDescription
RESOURCE_MAPPING.CREATEDA new migration mapping was created
RESOURCE_MAPPING.UPDATEDAn existing mapping was updated
RESOURCE_MAPPING.DELETEDA 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: 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.