Migrating 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

📘

Early Access!

Self service token migrations are currently in early access / preview! Before you are able to use the self-service process outlined below, you will need to opt in to this change to our API.

If you have any questions, do reach out to our support team using the button in the bottom right of our docs!

Codat's API allows you to provide tokens for a subset of our integrations during the creation of a data connection, which will allow you to self manage a migration.

This is currently supported for QuickBooks Online, BigCommerce, Zettle & TrueLayer; with more integrations being supported in the coming months.

To migrate, when creating a data connection you need to provide an additional connectionInfo object, that includes 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 are available on our Postman Collection here.

POST /companies/{id}/connections
{
  "platformKey" : "0000",
  "connectionInfo" : {
    "accessToken" : "0000-0000",
    "businessId" : "test-business-1234"
  }
}

🚧

Fetch on first link not supported

Fetch on first link isn't supported when performing self-service token migrations using the POST /companies/{id}/connections endpoint. After successfully creating a data connection with additional connectionInfo, you'll need to initiate a sync manually using the POST ​/companies​/{companyId}​/data​/all 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.

1. Supply migration and platform details

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

Responsibility: 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.

Responsibility: 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.

Responsibility: 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.

Responsibility: 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.

Responsibility: Codat support team.

6. Complete migration

Codat's support team:

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

Responsibility: Codat support team.


Did this page help you?