HubSpot Legacy Integration Audit Checklist: Find Every API Call, App and Business Dependency
By Robin Laseur
A HubSpot API audit checklist should identify more than legacy endpoint paths. It must connect each API call to its app architecture, credential, source code, owner, business workflow, replacement status, and test evidence. The result is a migration-ready inventory that technical and business teams can review together.
HubSpot’s 2027 transition gives most businesses time to migrate, but it also exposes a familiar problem: the integrations that matter most are not always the ones with the clearest documentation. A token may sit in middleware. A scheduled job may run once a quarter. One endpoint may quietly support lead routing, reporting, or order synchronization.
This checklist turns that scattered evidence into three linked registers you can copy into a spreadsheet. It is designed for the legacy API and app changes in HubSpot’s September 2026 announcement, rather than a general CRM implementation audit.
What should a HubSpot legacy integration audit cover?
A complete audit covers five areas: account and app inventory, observed API activity, source-code and automation discovery, business dependencies, and migration readiness. Each finding needs an owner and evidence. Recent traffic alone is insufficient because dormant, seasonal, fallback, or externally managed integrations may not appear in a short reporting window.
Use this quick scan before starting detailed discovery:
List every HubSpot production, sandbox, test, and developer account in scope.
Export or record every public app, private app, Service Key, and connected app.
Capture recent API activity and error logs from HubSpot and any middleware platform.
Search repositories and automation tools for
/v1/,/v2/,/v3/,/v4/, HubSpot SDK clients, portal IDs, app IDs, and secret names.Record every webhook, UI extension, app page, custom workflow action, and scheduled job.
Map each API call to the integration that sends it and the business process it supports.
Record the credential type, scopes, storage location, rotation owner, and last-used evidence.
Compare each legacy call with the supported replacement, including identifiers, payloads, responses, and associations.
Define the acceptance evidence and temporary operating route for each business-critical integration.
Assign a business owner, technical owner, decision, and next review date.
The checklist is complete when every discovered asset appears in a register and every register row has enough evidence for a migrate, replace, consolidate, retire, or investigate decision.
How do you establish the audit scope?
Start with accounts, environments, and systems rather than endpoints. This prevents a production-only review from missing test portals, developer accounts, middleware, archived repositories, or regional integrations. The scope should state which HubSpot accounts, external systems, vendors, and code locations the team has checked.
Account and environment checklist
Record the Hub ID, account name, region, subscription context, and environment type.
Identify the Super Admin or Developer Tools access holder for each account.
List production, sandbox, test, developer, and discontinued accounts that may still hold apps or credentials.
Record external systems that exchange data with HubSpot, including eCommerce platforms, ERP, data warehouses, BI tools, service platforms, advertising tools, and internal applications.
List middleware and automation platforms such as Workato, Make, Zapier, MuleSoft, n8n, cloud functions, and scheduled workers.
Identify external agencies, app vendors, and former delivery partners with current or historical access.
Define the evidence window for runtime logs and note what that period may exclude.
HubSpot’s migration guidance points users toward in-account migration information, but an account view cannot prove that you have inspected code outside HubSpot. Keep a written scope statement with the inventory so reviewers know which surfaces were checked and which remain unknown.
This scope also helps separate integration migration from wider HubSpot data management. Data quality may influence test evidence, yet this audit focuses on the code, apps, credentials, and workflows affected by the platform transition.
Which apps and credentials need to be inventoried?
Inventory every public app, private app, Service Key, OAuth installation, and Projects-based app before choosing a replacement. App type and credential type answer different questions. A data-only private integration may fit a Service Key, while webhooks, UI extensions, app pages, or multi-account distribution require a Projects-based route.
App architecture checklist
Record the app name, app ID, creation model, and whether HubSpot labels it as legacy.
Classify it as public, private, Marketplace, allowlisted, internal, or Projects-based.
Record every HubSpot account where the app is installed.
Confirm whether it uses webhooks, UI extensions, app cards, app pages, serverless functions, or custom workflow actions.
Identify the repository, project files, deployment process, and person or vendor who can release changes.
For Marketplace apps, record listing and certification requirements separately from API-version requirements.
Capture any app-specific migration guidance and unresolved feature parity.
The current HubSpot Developer Platform creates and deploys apps through projects and the HubSpot CLI. An app audit therefore needs source and deployment ownership, not only a screenshot of its account settings.
Credential checklist
Record the credential type: legacy private-app token, OAuth, static auth token, Service Key, Personal Access Key, or another documented key type.
Record the credential name and secret-store reference without placing the secret value in the audit sheet.
List granted scopes and compare them with scopes observed in use.
Record the accounts, systems, jobs, and environments that share the credential.
Capture creation, last-used, last-rotated, expiry, and revocation evidence where available.
Name the person responsible for rotation and emergency revocation.
Mark credentials with unknown consumers or broad scopes for investigation.
HubSpot’s Service Keys guidance distinguishes data-only, system-to-system access from app functionality. Service Keys can fit scheduled data syncs and internal scripts. They do not provide webhooks, UI extensions, app pages, or Marketplace distribution. Record actual functionality before selecting that path.
How do you find API calls that runtime reports may miss?
Combine observed activity with static discovery. Runtime logs show calls that happened during the selected period. Code, configuration, and automation searches show calls that could happen. Comparing the two exposes quiet code, seasonal jobs, fallback paths, shared credentials, and integrations whose logs sit outside HubSpot.
Runtime evidence checklist
Export recent API activity from HubSpot for every account in scope.
Capture method, path, timestamp, response status, app or credential identity, and calling account where available.
Review middleware, gateway, serverless, and application logs for HubSpot requests.
Check scheduled-job history for monthly, quarterly, annual, and campaign-specific executions.
Record rate-limit responses, authentication errors, retries, dead-letter queues, and manual reprocessing steps.
Note the start and end dates of every log source used.
Source-code and automation checklist
Search for literal paths containing
/v1/,/v2/,/v3/, and/v4/.Search for
api.hubapi.com, HubSpot SDK imports, client initialization, app IDs, portal IDs, environment-variable names, and secret references.Inspect code that constructs endpoint paths dynamically instead of storing full URLs.
Search CI/CD variables, cloud-function settings, container secrets, and infrastructure repositories.
Inspect low-code workflows, custom code actions, notebooks, BI connectors, spreadsheet scripts, and integration-platform recipes.
Review archived repositories and disabled workflows that can still be restored or redeployed.
Ask vendors for a versioned dependency list when source code is outside your control.
An older endpoint may also carry an identifier dependency. HubSpot’s v1 Lists API migration guide separates legacyListId from the current listId and cautions that the values can overlap across different lists. Record stored IDs, mapping logic, and downstream consumers beside the endpoint.
A review of your existing HubSpot integrations can help identify business systems to search, but the technical inventory should list the precise code or workflow that connects each one.
What technical details belong in the API register?
Create one API-register row for each distinct method and path used by an integration. Record the data contract, identifiers, scopes, replacement status, error behavior, and test case. Grouping an entire integration into one row hides endpoint-specific changes and makes test coverage difficult to verify.
API-call checklist
HTTP method and full path pattern.
Current version and target date-based version.
HubSpot object or capability used.
Trigger, schedule, volume pattern, and peak period.
Request fields, query parameters, filters, and pagination.
Response fields consumed by downstream code.
Object IDs, association IDs, list IDs, owner IDs, or custom identifiers stored elsewhere.
Authentication type and required scopes.
Rate-limit handling, retry rules, idempotency, and duplicate protection.
Expected error responses and monitoring signal.
Proposed replacement endpoint and documented parity status.
Test case, expected result, and evidence location.
Do not mark an endpoint as ready because a replacement URL exists. Readiness requires enough information to compare behavior. Request and response changes, pagination, identifiers, associations, permissions, and error handling can each alter the result even when the business action appears unchanged.
How do you connect the technical inventory to business dependencies?
Map every integration to the business process, systems, teams, timing, and acceptance evidence it supports. This turns a developer inventory into a planning document. A technically small endpoint can deserve early attention when it controls lead capture, consent, customer service, order data, or executive reporting.
Business-dependency checklist
Name the business process in plain language.
Record the source system, destination system, direction, and frequency of data movement.
Identify the system of record for every important field or object.
List the teams that create, consume, approve, or reconcile the data.
Record the business-critical period, acceptable delay, and temporary operating route.
Define how an interruption becomes visible to the business.
Record the reconciliation method, such as record counts, field comparison, association checks, workflow enrollment, or report matching.
Assign one business approver and one technical owner.
Link existing runbooks, diagrams, support tickets, and vendor documentation.
Record the decision: migrate, replace, consolidate, retire, or investigate.
The business owner should approve expected behavior. The technical owner should prove that behavior in a test environment. A green API response alone does not confirm that a contact reached the right list, an association remained intact, or a report received the same data.
If ownership is external, document the commercial and operational dependency as well. Flatline’s article on choosing a HubSpot partner provides broader criteria for assessing technical integration capability. The inventory still needs an internal approver who can define the business outcome.
Copyable HubSpot integration audit template
The template uses three tabs because integrations, API calls, and business dependencies have different levels of detail. Give every integration a stable Integration ID, then use that ID to join the tabs. Copy each header into a separate spreadsheet tab or CSV file.
Tab 1: Integration register
Tab 2: API-call register
Tab 3: Business dependency and acceptance register
Use controlled values where possible:
Current Status: Active, Dormant, Seasonal, Disabled, Unknown.
Parity Status: Confirmed, Partial, Unavailable, Unchecked.
Decision: Migrate, Replace, Consolidate, Retire, Investigate.
Approval Status: Not Ready, Ready for Planning, Ready for Build.
Assign one person to control the register structure while technical and business owners supply evidence. This prevents separate teams from creating overlapping names for the same integration. Where several jobs share one app or credential, keep one Integration ID only when they also share ownership and deployment. Give independently deployed or approved jobs separate IDs, even if they use the same token.
Review open questions in a short working session rather than treating the sheet as a passive document. Each unresolved field should end with an owner, evidence request, or investigation task. A blank cell without an action will usually remain blank when planning begins.
Do not store access tokens, client secrets, or Service Key values in the worksheet. Store only the secret-manager reference and the responsible owner.
When is the audit ready for migration planning?
An integration is ready for migration planning when its current behavior, target path, owners, dependencies, and acceptance evidence are documented. If the team cannot explain what the integration does or how to prove equivalent behavior, the correct status is Investigate rather than Ready for Planning.
Use this gate for each Integration ID:
Gate | Ready when | Hold when |
|---|---|---|
Discovery | Runtime and static searches are complete for the declared scope | Accounts, repositories, automations, or vendors remain unchecked |
Technical contract | Calls, payloads, responses, identifiers, scopes, and target paths are recorded | Replacement parity or downstream field use is unknown |
Business dependency | Process, system of record, affected teams, and acceptable delay are agreed | The business consequence cannot be stated |
Ownership | Business approver and technical owner have accepted responsibility | Ownership sits with a former employee, unknown vendor, or shared inbox |
Evidence | Test case, expected result, reconciliation, and evidence location exist | Success is defined only as an HTTP 2xx response |
Continuity | Temporary operating route or rollback boundary is documented where needed | A critical workflow has no agreed response to interruption |
An incomplete row is not a reason to guess. It is evidence that discovery work remains. Keep those unknowns visible so estimates and timelines reflect the real scope.
With the registers complete, three reads come next: what HubSpot is changing and when for the context, the migration plan for sequencing, testing and rollback, and the choice between Service Keys and Projects-based apps for each integration you need to replace.
Key takeaways
Audit accounts, apps, credentials, code, automation platforms, API calls, and business workflows as linked evidence rather than separate lists.
Combine runtime logs with source and configuration searches. Each method finds exposure the other can miss.
Use one row per API method and path, then record the payload, response fields, identifiers, scopes, replacement, and test case.
Keep three linked registers for integrations, API calls, and business dependencies. The
Integration IDconnects technical evidence to operational ownership.Move an integration into migration planning only when the target path, owners, acceptance evidence, and continuity route are clear.
The value of this audit is the quality of the handoff it creates. A complete inventory lets the next planning stage sequence work by business consequence and technical uncertainty. It also gives reviewers one place to challenge assumptions before those assumptions reach production.
Related articles
