Migrate To Railz

Welcome to the Railz migration guide. Whether you've partnered with another financial data integration provider or have built your own integrations, you're in the right place.

Our managed migration process allows you to effortlessly transfer your existing customer connections to Railz, without requiring them to go through the reauthorization process. This guide will walk you through the steps to ensure your transition is as smooth as possible.

Why Migrate to Railz?

• More Data Coverage: Expand the horizons of your data collection with comprehensive coverage across various platforms and services.
• Analytics Insights: Gain invaluable insights into your business data through Railz's robust analytics features.
• Enhanced Normalization: Benefit from standardized data formats, making it easier for you to integrate and analyze the information.
• Managed Migrations: Our team takes care of the migration process from start to finish, letting you focus on what truly matters—your business.

Migration Checklist

Before diving into the migration process, ensure you have the following:

• Ensure you enter the same Client ID and Secret that you used when obtaining the tokens for each business into the dashboard through the integrations page for each service provider.
• The business names and the accounting service providers (ASP) they are connected to.
• Access Tokens from all of the ASPs.
• Refresh Tokens from all of the ASPs.
• Provide the Account ID, Business ID, Realm ID or Tenant ID of the ASPs.
• Coordinate a time when the migration can take place. Railz will run the migration on your behalf once all the information has been provided.

Migration Process

Railz supports self-managed and managed migration processes, providing flexibility to handle migrations according to your capabilities and preferences.

⚠️

Client ID and Client Secret

Ensure you use the same Client ID and Secret that you used when obtaining the tokens for each business. Add these via the Railz dashboard.

Self-Managed Migration

Railz offers a self-managed migration feature that allows you to independently handle the transition of your business connections via our API.

How to Perform a Self-Managed Migration

1. Create or Retrieve a Business: Begin by either creating a new business with POST /v2/businesses or retrieving an existing business using GET /v2/businesses to obtain the businessUuid.

2. Initiate Migration: Use the POST /v2/businesses/{uuid}/connection/migrate endpoint to migrate the business connection. Replace {uuid} with the businessUuid obtained in the previous step.

   Request Example:

   HTTP

   POST /v2/businesses/{uuid}/connection/migrate
   

   Body Parameters:

   JSON

   {
     "serviceName": "quickbooks",
     "accessToken": "string",
     "refreshToken": "string",
     "accountId": "string"
   }
   

   Replace "serviceName", "accessToken", "refreshToken", and "accountId" with the respective details for the connection you are migrating. Ensure that the refresh token has not expired before initiating the migration. API Reference can be found here.

Considerations for Self-Managed Migration

• Data Syncing Post-Migration: Once the migration is successful, manually initiate a data sync using:

  HTTP

  POST /v2/data/sync
  

  This step is crucial to ensure that all migrated data is updated and available through Railz. API Reference can be found here.

• Monitor Migration Status: After initiating the migration, you can check the data sync status to monitor the progress of the synchronization:

  HTTP

  GET /v2/data/syncStatus?connectionUuid=<the response from the migration endpoint>&requestId<id from datasync post>
  

  API Reference can be found here.

Managed Migration Process

Railz also offers a managed migration process to assist you in transitioning seamlessly. Our team will handle the migration based on the information you provide.

Pre-Migration Steps

• For Competitor Users:

  • Contact Your Existing Provider: Securely request access to your authorization keys.
  • Provide Key Information: Submit the acquired keys to Railz through a secure channel.

• Data Preparation: Compile all necessary data and token information, as per your existing service provider.(see table below for details).

🚧

Automatic migration cannot be done for these Service Providers:

• QuickBooks Desktop
• Oracle Netsuite
• Sage Intacct

For these providers, contact us for more details.

Required Information by Service Provider

Note: Based on the table above, accountId in the API refers to different IDs such as Realm ID, Tenant ID, Account ID, etc., depending on the service provider.

Migration Steps

Potential Issues and Troubleshooting

Migration processes are often complex and can sometimes run into issues. Below are some potential problems that you could encounter during your migration to Railz, along with suggestions for resolving them.

If you run into an issue not covered here, please reach out to our support team for personalized assistance.

Other Migration Alternatives

If the managed migration process isn't suitable for your needs, or if you'd prefer to take a different approach, another alternative is to implement Railz's connection flow into your application. This would involve setting up the Railz connection process in your application and inviting your businesses to reconnect their service providers through this new flow.

Advantages

• Complete Control: You have complete control over the user experience.
• Immediate Authorization: Businesses can connect immediately without waiting for a scheduled migration.
• Refreshed Data: By having businesses go through the authorization flow again, you ensure that all data permissions and scopes are up-to-date.

Steps to Implement

• Implement Railz Connection Flow: Follow the documented steps here.
• User Notification: Notify your businesses about the new update and guide them to reconnect their accounts via the new flow.

Frequently Asked Questions (FAQ)

• Is self-managed migration possible?
  • Currently, Railz only offers managed migrations. Self-managed migrations are coming soon.
• How long will the migration process take?
  • The migration duration varies. It's best to consult with our team for an accurate timeframe.

Get Support

For any migration-related queries or issues, contact our support team.

Helpful Links

API docs
Help centre