Migrate from v3 to v4

What Changed

client.crm.contacts.basicApi.create(...)

client.crm.contacts.coreApi.create(...)

deal.properties.dealname

deal.properties.dealname

client.crm.contacts.batchApi.create(...)

client.crm.contacts.batch.coreApi.create(...)

client.crm.objects.contacts.getById(...)

client.crm.objects.contacts.getById(...)

client.crm.objects.companies.basicApi.update(...)

client.crm.objects.companies.coreApi.update(...)

Migration Steps

1. 1

   Review v4 API Documentation

   config

   Thoroughly read the official HubSpot API v4 migration guide and release notes. Understand the key changes, new features, and deprecated functionalities.

   • ↳Pay close attention to the changes in the Contacts, Companies, Deals, and Tickets APIs.
   • ↳Note any changes to authentication or rate limiting.
2. 2

   Update SDK/Client Library

   code

   Install or update your HubSpot client library to the latest version that supports v4. This ensures you have access to the new endpoints and methods.

   • ↳Check your package manager (npm, pip, etc.) for the latest version.
   • ↳Consult the SDK's changelog for specific upgrade instructions.
3. 3

   Adapt Endpoint Calls

   code

   Modify your code to use the new v4 endpoint structures and method names. This is the most significant code change required.

   • ↳Update calls to CRM object endpoints (contacts, companies, deals, etc.).
   • ↳Adjust calls to batch and search endpoints.
4. 4

   Handle Property Changes

   code

   Update references to HubSpot object properties. Some standard properties might be renamed, removed, or have changed format.

   • ↳Use the `crm.properties.coreApi.get_page` endpoint to fetch current property definitions.
   • ↳Test thoroughly to ensure data mapping remains correct.
5. 5

   Implement Error Handling Updates

   code

   Review and update your error handling logic. v4 may introduce new error codes or change the format of error responses.

   • ↳Check for new `error_type` values or changes in the `messages` array.
   • ↳Ensure your retry mechanisms are still effective.
6. 6

   Configure API Keys/OAuth

   config

   Verify that your API keys or OAuth configurations are still valid and compatible with v4. No major changes are expected here, but it's good practice to confirm.

   • ↳Ensure your app's scopes are still appropriate.
   • ↳If using OAuth, ensure token refresh logic is robust.
7. 7

   Perform Unit and Integration Testing

   test

   Write comprehensive unit and integration tests covering all modified API interactions. Ensure data is being created, read, updated, and deleted correctly.

   • ↳Mock API responses to isolate specific test cases.
   • ↳Test edge cases and error scenarios.
8. 8

   Deploy to Staging Environment

   deploy

   Deploy your updated integration to a staging or development environment that mirrors your production setup. Conduct thorough end-to-end testing here.

   • ↳Use a separate HubSpot portal for staging if possible.
   • ↳Monitor logs closely for any unexpected behavior.
9. 9

   Monitor Production Rollout

   deploy

   Gradually roll out the changes to your production environment. Monitor key performance indicators and error logs closely during and after the rollout.

   • ↳Consider a canary release or phased rollout.
   • ↳Have a rollback plan in place.
10. 10

    Verify Data Integrity

    verify

    After the migration, perform checks on your HubSpot data to ensure no records were lost or corrupted. Compare critical data points before and after the migration.

    • ↳Spot-check a sample of records.
    • ↳Run validation queries against HubSpot data.

Testing Checklist

1. 1.

   Contacts Creation/Update

   Verify basic contact create, read, update operations using v4 endpoints.

2. 2.

   Deal Association

   Test creating/updating deals and associating them with contacts.

3. 3.

   Custom Object Operations

   If using custom objects, ensure all CRUD operations function correctly.

4. 4.

   Batch Operations

   Test creating or updating multiple records in a single batch request.

5. 5.

   Property Field Handling

   Verify that custom and standard properties are correctly read and written.

6. 6.

   Search and Filtering

   Test searching for records using various criteria and filters.

7. 7.

   Error Response Handling

   Simulate API errors (e.g., invalid data) and check if your error handling is correct.

Common Mistakes