This is a staging build of the docs
Skip to main content

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.

Authorize connection
  PUT /companies/{companyId}/connections/{connectionId}/authorization
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 offers a managed migration pathway.

Supported integrations

We currently have supported migrations from the following platforms: FreeAgent, FreshBooks, QuickBooks Online, Shopify, Wave, 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.

The migration process usually involves the following steps.

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.

StepDetailsResponsibility
1. Supply migration and platform detailsSupply all the required details for the specific platform to the Codat support team.Your company
2. Schedule the migrationAgree 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 detailsAdd Codat’s callback URL to the application registered with your platform provider.Your company
4. Disable data syncingDisable 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 companyCodat's support team imports the name and token for a single company and performs an end-to-end test to make sure:
- No reauthorization is required.
- Data syncs complete correctly.
Codat support team
6. Complete migrationCodat's support team:
- Migrates the remaining companies.
- Performs end-to-end tests.
- Completes a handover.
Codat support team

Was this page useful?
❤️
👍
🤔
👎
😭