Migrate to Codat

Learn how to migrate existing authorization tokens from your existing integrations to Codat

If you're new to Codat but have already built and use an OAuth application with one of our supported integrations, you're in the right place. Codat's token migration process allows you to seamlessly migrate your customers' connections from a self-managed integration to Codat—without your customers needing to reconnect.

This page describes the information we'll need from you, and provides an overview of the migration process.

Self service migrations

Codat's API allows you to provide tokens for a subset of our integrations which will allow you to self manage a migration.

Self service token migration is currently supported for over twenty of our integrations, with more being added in the coming months. To view an up-to-date list, check out the available integrations in the OAuth Token Migrations section of our Postman collection.

Before you migrate a token, the Company and data connection must be created. This is required because the companyId and connectionId are parameters in the PUT token migration URL (see below). You can create the Company using a POST call to the Create company endpoint. The connection can be created using the Create connection endpoint.

To migrate, use the PUT connections endpoint. You will need to provide the integration specific information such as the organization ID and OAuth tokens that Codat should use. Because these are different for each integration, examples of the format required for the integrations available are listed in the Postman Collection linked above.

PUT /companies/{companyId}/connections/{connectionId}/authorization
{
  "accessToken": "0000-0000",
  "businessId": "test-business-1234",
}

🚧

Syncing data post-migration

After successfully updating a connection with valid credentials, you'll need to initiate a sync manually using the POST ​/companies​/{companyId}​/data​/all endpoint.

Fetch on first link isn't supported when performing self-service token migrations using the PUT /companies/{companyId}/connections/{connectionId}/authorization endpoint.

Managed migrations

For other platforms where we do not yet support the self service migration route, or if you have special considerations or concerns, Codat's solutions team offer a managed migration pathway.

📘

Supported integrations

We currently have supported migrations from the following platforms: FreeAgent, FreshBooks, QuickBooks Online, Shopify, Wave, Xero, and Zoho Books.

We don't have a standard migration process for our other integrations, but are happy to explore possible solutions. Please get in touch with your solutions engineer if you need to discuss migrating one of these integrations.

You need to supply:

  • A spreadsheet - .xls or .csv file - that includes names of the companies that Codat need to migrate, and their token details.
  • Secure credentials for your application, for example, client ID and client secret.

The exact details of tokens and credentials varies between different platforms; please contact your solutions engineer or our support team to discuss the specific details requirements for your migration.

The migration process usually involves the following steps. We recommend that you don’t start migration until you've set up the integration in Codat, and done some initial testing.

👍

Plan your migration

Every migration is different so please make sure you talk to your solutions engineer, or contact our support team as early as possible to discuss and plan your migration.

Step

Details

Responsibility

1. Supply migration and platform details

Supply a spreadsheet, with the details described above, to the Codat support team.

Your company

2. Schedule the migration

Agree a time when the migration can take place. Based on your company's data, Codat's support team estimates how long the migration will take.

Your company and the Codat support team

3. Update your application details

Add Codat’s callback URL to the application registered with your platform provider.

Your company

4. Disable data syncing

Disable data syncing in your existing application for all companies that you have chosen to migrate. This is to prevent tokens from becoming invalid.

Your company

5. Migrate first company

Codat's support team imports the name and token for a single company and performs an end-to-end test to make sure:

  • No reauthorisation is required.
  • Data syncs complete correctly.

Codat support team

6. Complete migration

Codat's support team:

  • Migrates the remaining companies.
  • Performs end-to-end tests.
  • Completes a handover.

Codat support team