> ## Documentation Index > Fetch the complete documentation index at: https://docs.synctera.com/llms.txt > Use this file to discover all available pages before exploring further. # Bank Migration Guide > Use the Migration Mapping API to link old and new resources when migrating from one sponsor bank to another on the Synctera platform. 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](/docs/create-a-personal-customer) * [Create a Business Customer](/docs/create-a-business) * 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. ```json theme={"system"} { "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. 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`. ```shell theme={"system"} 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. ```json theme={"system"} { "persons": [ { "id": "abc12345-0000-0000-0000-000000000001", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ], "next_page_token": "..." } ``` For each customer, retrieve their accounts so you have the full picture of what needs to be recreated. ```shell theme={"system"} 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. 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. ```shell theme={"system"} 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. ```json theme={"system"} { "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. 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. ```shell theme={"system"} 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`. 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. ```shell theme={"system"} 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: ```json theme={"system"} { "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 a corresponding mapping for each account, linking the old account ID to the new account ID. ```shell theme={"system"} 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 ```shell theme={"system"} 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 ```shell theme={"system"} 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. ```shell theme={"system"} 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). ```shell theme={"system"} 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 ```shell theme={"system"} 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. | 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](/docs/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: * [List migration mappings](/reference/listmigrationmappings) * [Create a migration mapping](/reference/createmigrationmapping) * [Get a migration mapping](/reference/getmigrationmapping) * [Update a migration mapping](/reference/updatemigrationmapping) * [Delete a migration mapping](/reference/deletemigrationmapping) ## 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.