Skip to main content
Legacy CRM cards will be sunset on Oct 31, 2026. This means if your app currently contains a legacy CRM card, it must be migrated to an app card before the sunset date to avoid interruptions for your end users. App cards built with React can do everything legacy CRM cards can do, but offer more advanced customization options. This guide walks you through how to build a replacement app card and replace your legacy CRM card with an app card in user accounts. Once your card is migrated, your users will not need to take action to adopt the replacement app card.

​
Prerequisites

​
Create an app card to replace the legacy CRM card

To start the migration process, create an app card that will replace your legacy card.
Please note: it’s highly recommended to build your app card in a separate testing environment prior to adding it to your app.
When creating your replacement app card, you can either:

​
Redesign by creating a new app card

To start from scratch, follow the instructions to create a new app card. React-based app cards can include more design elements than your existing legacy card, such as images, forms, and tables. With more UI components and data fetching capabilities, app cards give you the opportunity to design dynamic experiences embedded within HubSpot to meet your users where they work. Use the Figma design kit to plan your designs, or refer to the components reference to get started. During beta testing, you can enable the app card for a subset of your users by using feature flags. Once your new app card is ready, you can add it to the app with the legacy CRM card to begin the migration process.

​
Convert a legacy CRM card into an app card

If you want to quickly convert your legacy CRM card to an app card, refer to the Legacy CRM Card Converter GitHub sample for guidance. This sample provides an app card that works like a legacy CRM card to help you test and develop a new app card before migrating. The converter fetches data from an API endpoint to display tiles, expandable content, and action buttons that work almost identically to your legacy CRM card. Refer to the README.md for instructions and more details, including the differences between the legacy CRM card and the converter app card. Once your new app card is ready, you can add it to the app with the legacy CRM card to begin the migration process. If you want to redesign the card later, you can update the app card design as needed.

​
Add the app card to the app with the legacy CRM card

Once you’ve set up the replacement app card, add it to the project with the legacy CRM card.
  1. Copy the contents of the cards folder of the development project.
  2. Paste the card content in the cards folder of the app with the legacy CRM card.
  3. Upload the project (hs project upload). The uid of the replacement card will be shown as processing during build and deploy.
  4. Verify the app card displays in installs with scopes by adding it to views.
Please note: if your migrated app is listed on the HubSpot Marketplace, all app cards are automatically hidden from all users, allowing for beta testing during development. To enable the app card for a subset of your users for testing, use the hs-release-app-cards feature flag. Once you’re ready to replace the card for release to all customers, delete the feature flag. The feature flag must be deleted prior to using the migration endpoint. If you’ve used the hs-hide-crm-cards flag, it must also be deleted prior to migration. Use the feature flag API to delete the flags from your app.

​
Replace the legacy CRM card with the app card in user accounts

Once the new app card is included in your app, migrate the legacy card to the new app card.
  • During the migration: users will continue to see the legacy CRM card in their views. Some users may temporarily see both the legacy CRM card and the app card in some views, but they will not lose access to the cards in your app.
  • When a migration is complete: the legacy CRM card will be replaced by the app card in all user views. The legacy CRM card will be hidden and users will not be able to add it to views.
Please note: once the card view migration has started, it cannot be reversed. Be sure the app card works as intended through beta testing before replacing the card in all user views.
Please note: if your legacy CRM card supports tickets, an app card must be enabled for the helpdesk.sidebar location for it to appear in the help desk workspace. This means you need two app cards to support existing legacy CRM cards for tickets: one for the crm.record.sidebar location and one for the helpdesk.sidebar location. They will need different titles, and you need both app card IDs to undertake migration.

​
Replace a card in the projects UI

To migrate from within HubSpot:
  1. In your HubSpot account, navigate to Development. Then, click the name of your project.
  2. If your project has legacy CRM cards, a migration banner is displayed with a list of the cards to migrate. At the bottom of the banner, click Review & migrate.
Click Review & Migrate
  1. In the right panel, review the migration details, then click Next to begin a card migration.
  2. Select the legacy CRM card to migrate.
  3. Select the replacement app card to which your legacy card will be migrated. App cards are only shown as options if they are compatible replacements for the legacy card.
    • If your legacy CRM card supports tickets, select a Helpdesk sidebar card to replace the card displayed in the help desk workspace.
    • If you’ve selected a replacement card used in a previous migration, select the Allow consolidating multiple legacy CRM cards into one app card checkbox to confirm that you’re consolidating multiple legacy cards into one new app card.
  4. Click Migrate, then in the dialog box, click Migrate to confirm. Once the migration has started, it cannot be stopped or reversed.
Select replacement card
  1. The migration process will begin and progress is displayed in the panel. If your app has many installs, it may take a few minutes.
  2. When the migration is finished, the panel will show the status Migration Complete.
    • To delete the legacy CRM card, click Delete legacy card. In the dialog box, click Delete to confirm. You can delete at a later time or the card will be automatically deleted when legacy CRM cards are deprecated.
    • To begin migrating another legacy CRM card, click Migrate another card.
Card migration complete

​
Replace a card with the migrate views API

To use the migrate views API endpoint to replace legacy CRM cards:
  1. Copy the values for the following fields: appId, appCardId, legacyCrmCardId, and if your legacy CRM card supports tickets, helpdeskAppCardId. Retrieve cards to get the legacy card ID and view projects in HubSpot to get the app, app card, and help desk app card IDs.
Find app ID in projects tool
Find app card ID in projects tool
  1. Make the following call to the migration endpoint (/crm/v3/extensions/cards-dev/{appId}/views/migrate).
curl -X POST 'https://api.hubapi.com/crm/v3/extensions/cards-dev/{appId}/views/migrate?hapikey={developerApiKey}' \
  -H 'Content-Type: application/json' \
  -d '{"legacyCrmCardId": "{legacyCrmCardId}", "appCardId": "{appCardId}", "helpdeskAppCardId": "{helpdeskCardId}"}'
By default, the migration endpoint blocks requests if the target appCardId is already associated with another legacy CRM card migration. This prevents multiple legacy CRM cards from being migrated into a single app card. To consolidate multiple legacy CRM cards into a single app card, set allowDuplicateAppCardIds in the request body to true.
  1. The migration process will begin and the API will return a message summarizing the progress. View updates are processed asynchronously. You can safely call the endpoint again with the same request body to check progress. Retrying the endpoint will not duplicate work or cause adverse effects.
Migration Underway: X of X installs still processing. This process takes longer for high install count apps, or for customers with unique view setups. Re-hit this endpoint with the same body to see progress.
The migration should complete within a few minutes. If the migration takes longer than expected, the endpoint will return an extended status message.
  1. Once the migration is complete, the following message will be returned.
Migration Complete: All customer views have been migrated to App Card X. Legacy CRM Card X has been hidden from all customers and is ready to be deleted. Delete the card through the API: `https://developers.hubspot.com/docs/api-reference/legacy/crm/extensions/crm-cards/delete-crm-card`.
Once the card is replaced and users are unable to add the legacy CRM card to views, the legacy CRM card can be deleted.

​
Delete unused legacy CRM cards

It is safe to delete a legacy CRM card once a migration is complete. This process will have no impact on end users and they’ll automatically have access to the new app card. If not deleted, the legacy CRM card will continue to exist in the backend until it is automatically deleted after the deprecation of legacy CRM cards on Oct 31, 2026.

​
Delete legacy CRM cards in the projects UI

To delete a migrated card from within HubSpot:
  1. In your HubSpot account, navigate to Development. Then, click the name of your project.
  2. At the bottom of the migration banner, click Review & migrate.
  3. In the right panel, click Next.
  4. Click to expand the Previously migrated cards section.
  5. Next to the card’s name, click Delete. In the dialog box, click Delete to confirm.
Delete migrated legacy CRM cards

​
Delete legacy CRM cards via API

To delete a replaced legacy CRM card, make a DELETE request to /crm/v3/extensions/cards-dev/{appId}/{cardId}?hapikey={developerApiKey}. Include the appId and cardId values of the legacy CRM card. Once the legacy CRM card is deleted, there will no longer be warnings about the legacy CRM card existing in your app.
Last modified on June 11, 2026