Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 swap your legacy CRM card for 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 swap 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.

​
Swap the legacy CRM card for the app card in user accounts

Once the new app card is included in your app, you can swap it with the legacy CRM card so the new card appears for your users. Once swapped, the legacy CRM card will be replaced by the app card in all user views. Once the swap is complete, the legacy CRM card will be hidden and users will not be able to add it to views.
Please note: once the card view swap has started, it cannot be reversed. Be sure the app card works as intended through beta testing before swapping in all user views.
To use the migrate views API endpoint to swap the 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
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.
  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. During this time, users who have not yet been swapped to the new app card 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. Users will not lose access to the cards in your app.
  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 the 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. To delete a swapped 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 is deleted, there will no longer be warnings about the legacy CRM card existing in your app.
Last modified on April 24, 2026