How do I migrate my V2 organization, applications, accounts and objects to V3

Please ensure that the admin email address on the V2 org is also an admin in the V3 dashboard.

Please ensure you are aware of all the changes between V2 and V3, especially the fact that there are large Rate Limit Reductions.

You can either re-create some of these objects or choose to migrate via our API.

Organisation Migration

What is Migrated

• Billing details

How to Migrate

1. Admin Accounts Match:

   • If the admin accounts match when registering on V3, you should see the V2 Org automatically in the V3 dashboard (top right on your profile picture).

2. Admin Accounts Match After Creation:

   • If the admin accounts only match after the creation of the dashboard you can use the API.

Application Migration

What is Migrated

• Redirect URLs (as web platform)
• Branding (name, website_url, icon_url, description)
• Required to allow object V2 to V3 mapping for reply_to_message
• Google connector (Google client id/secret)

What is NOT Migrated

• Webhooks
• Scopes, you will need to add these to the connector.
• Hosted Auth white labeling
• OAuth settings (i.e., connectors)

Note: This is to ensure customers have the correct scopes.
Note2: You can migrate to multiple V3 place holder applications.

How to Migrate

1. Create Placeholder Application:

   • Create a placeholder application for each application you wish to migrate.

2. Use the API:

   • First link the APPS.
   • Then copy the settings across

Dashboard Account Migration

Sadly, we currently have no means to migrate admins from one org to another due to new Role-Based Access Control (RBAC) roles. Users will need to be re-invited.

We will be adding more roles in future such as:

• Billing
• Support
• Admin (per app)

Connected Account Migration

• You can either slow migrate, where you change the Auth URL and over time customers migrate
• Alternatively, you can use our clone tool which clones accounts from V2 to V3

Please see the V3 account migration documentation.

Object Migration

• V2 Object ID's can be used in the V3 GET endpoints (it will increase the latency by 1 second)
  • This functionality will continue to work for 1 year after V2 EOL in October 2023
  • Will be released in Late June.
• We also have a tool that allows you to migrate V2 Object ID's to V3 ID's, Object ID translation from V2 to V3 documentation.

Virtual Calendars

We will be announcing this tool within the next two weeks, we can migrate the calendars and events.

Scheduler Migration

Slugs will be automatically migrated for accounts that have been migrated via the account migration tool. You will find a list of old slugs that you can import, this is in development and expected Mid July. For updates on Scheduler v3, please see the Scheduler v3 Interactive Roadmap.

Note: Slug URL will change, you can apply any name to the slug that you wish, providing you own the domain, scheduler is a front end component in API v3 vs a Nylas domain hosted tool in API V2.

Resources:

Issues and Differences During Migration from V2 to V3 - Best Practices

Migrating accounts from V2 to V3

Updated July 16, 2024 08:25