HubSpot organizes a large surface around two central domains you will use most: CRM objects (contacts, companies, deals, tickets, custom objects, etc.) and the platform resources that reference them (lists, properties, pipelines, associations, files, marketing assets, events, apps). Understanding how those domains link and which IDs each operation needs makes most user requests straightforward.

High-level organization and key identifiers

HubSpot groups resources by service area and by object type. The patterns you rely on are:

• CRM object operations are namespaced under /crm/v3/objects (create/read/update/delete/search) and accept both standard object types (e.g. contacts, companies, deals) and custom object type IDs like 0-1, 0-3, 0-162. When you see a path parameter named objectType it expects the object type string (or type id) used throughout the CRM endpoints.
• Associations are a distinct concept from objects. Creating or removing links between objects uses dedicated association endpoints (v3 and v4). v4 association endpoints return labeled association lists and are the go-to when you need association labels or batch operations.
• Lists have their own notion of ID (ILS IDs). Legacy list IDs exist; use the id-mapping endpoints when needed. List membership and membership-management endpoints are separate and commonly used when synchronizing contacts to lists.
• Many resources exist in both single and batch forms (for create/read/update/upsert). Prefer batch endpoints when the user asks to process many records at once.

Common identifiers you will repeatedly need

• objectType and objectId — object type (e.g. contacts or 0-1) and its id. Many read/update/delete endpoints require both.
• listId — an ILS list id used by list membership endpoints. Legacy list ids can be translated using the id-mapping endpoint.
• campaignGuid — marketing campaign UUIDs used by marketing endpoints.
• appId — numeric ID for app-scoped resources (media-bridge, custom actions, feature flags, timeline event templates).
• portalId — Hub (account) id used for account-level feature flag state and some settings.
• fileId, folderId, path — files can be accessed by id or by path; some file endpoints accept the environment (draft/published) plus a path parameter.
• externalEventId vs objectId (marketing events) — externalEventId references the event in an external system, while objectId is HubSpot’s internal id.
• token, access token and refresh token appear in OAuth/token endpoints and in SMTP/token management.

Entry points — what to call first to get the IDs you need

Start with these reads when you need IDs to act on other resources:

• Get account and portal info: GET /account-info/v3/details to understand account metadata and to find portalId when needed.
• Owners: GET /crm/v3/owners to find an ownerId for assigning records.
• Object schemas and properties: GET /crm-object-schemas/v3/schemas_getAll or GET /crm/v3/properties/{objectType} to discover field names and canonical objectType values (especially for custom objects).
• Lists: GET /crm/v3/lists/_getAll or GET /crm/v3/lists/{listId} / id-mapping to find ILS listId and to translate legacy ids.
• Search endpoints: POST /crm/v3/objects/{objectType}/search and POST /crm/v3/objects/contacts/search are the practical way to find records by email, name, or other properties when you don’t already have an id.
• Files: GET /files/v3/files/{fileId} or GET /files/v3/files/stat/{path} to map file paths to ids; POST /files/v3/files_upload returns a fileId for new uploads.

Use these reads first so you can supply objectId, listId, appId, fileId, campaignGuid in subsequent calls.

Common real-world workflows and the sequence of operations

Below are patterns you’ll use to satisfy typical user requests.

Create or update a CRM record (contact/company/deal)

• If the user gives an email or external id: use POST /crm/v3/objects/{objectType}/search (or contact-specific search) to find an objectId.
• If not found and the user wants creation: POST /crm/v3/objects/{objectType} to create.
• To change fields: PATCH /crm/v3/objects/{objectType}/{objectId} (or PUT replace where available); supply idProperty when you intend to address records by a unique property instead of id.
• For many records at once, use batch endpoints (POST /crm/v3/objects/{objectType}/batch/create / /batch/upsert).

Linking objects (associations)

• To list associations from an object: GET /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType} (v3) or GET /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType} (v4). Use includeFA=true when you need full associated objects rather than only ids.
• To create a single association: PUT /crm/objects/v3/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType} (v3 style) or PUT /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId} (v4). Use the v4 batch endpoints when associating many pairs.
• Association labels and limits: use the association definitions endpoints to inspect available labels and to create custom-label configurations.

Manage list membership

• To create a list: POST /crm/v3/lists/_create.
• To add/remove members: use PUT /crm/v3/lists/{listId}/memberships/add_add, remove_remove, or add-and-remove_addAndRemove for atomic add/remove operations. For bulk operations prefer batch endpoints or the memberships bulk endpoints.
• Use GET /crm/v3/lists/{listId}/memberships_getPage to view members.
• Important: listId here is the ILS id; translate legacy ids with the id-mapping endpoints if needed.

Files and signed access

• Upload: POST /files/v3/files_upload returns a fileId.
• Metadata: GET /files/v3/files/{fileId} or GET /files/v3/files/stat/{path}.
• Private files: request a signed URL via GET /files/v3/files/{fileId}/signed-url_getSignedUrl with expirationSeconds.

Imports and exports (asynchronous)

• Start import/export: POST /crm/v3/imports/_create or POST /crm/v3/exports/export/async_start.
• These return an id or task; check status with the task/status endpoints such as GET /crm/v3/exports/export/async/tasks/{taskId}/status_getStatus. Treat 202-style flows as long-running and poll the provided status endpoint.

Marketing emails, campaigns, and events

• Campaigns use campaignGuid (UUID). Use GET /marketing/v3/campaigns/ and GET /marketing/v3/campaigns/{campaignGuid} to locate campaign data and assets.
• Marketing events have two ids: externalEventId (external system) and objectId (HubSpot). Many event endpoints accept an externalAccountId query parameter when operating by external id; when you have objectId, use the object-specific endpoints.
• To upsert events from an external system: PUT /marketing/v3/marketing-events/events/{externalEventId}_upsert (pass externalAccountId in queries when required).
• For attendance/participation changes, use the event attendance endpoints keyed by externalEventId or objectId depending on context.

Feature flags and app-scoped resources

• App-scoped (feature-flags, action definitions, timeline templates, media-bridge) use appId. Many operations require a numeric appId and will only operate on app-owned resources.
• Account-level flag state uses portalId and can be listed, set, or cleared via the portals endpoints under feature-flags. Batch portals endpoints exist for mass changes.

Scheduler / meetings

• Meeting pages are identified by slug. Booking requires timezone and often expects additional payload fields; availability queries require slug and timezone.

Non-obvious patterns and gotchas

These are the recurring pitfalls that are not obvious from raw signatures.

• Archive vs delete vs GDPR-delete

  • Many delete endpoints are soft-deletes and are labeled _archive in the path. Most GET endpoints accept archived (default false) to include archived records. There are separate GDPR-delete endpoints for irrevocable deletion.

• idProperty exists on many CRM read/update endpoints

  • You can supply idProperty to operate on a record by a unique property (for example email for contacts) instead of the internal objectId. Use this when the caller only supplies an external unique key.

• Two association APIs (v3 vs v4)

  • v4 association endpoints return labeled association collections and support larger-batch operations with a limit default of 500. Use v4 when you need labels or multi-association responses. Use v3-style endpoints when working with the older association patterns or when code paths already expect that shape.

• Lists and list IDs

  • The list APIs use an ILS listId. Legacy list ids exist; translate them via GET /crm/v3/lists/idmapping_translateLegacyListIdToListId or the batch translation endpoint.

• Batch endpoints are the norm for scale

  • For bulk creation, updates, or deletes use the /batch or search endpoints rather than looping single-item endpoints. Many batch endpoints return a batch response wrapper with individual item results.

• archived filtering and default limits

  • Most listing endpoints default to archived=false. Many list endpoints also have conservative default limit values; if the user asks for “all” records, you must page through results (use the paging cursor values returned by the API). Note some endpoints cap the maximum limit (e.g., lists membership endpoints cap at 250 for certain calls).

• Async flows use task ids and separate status endpoints

  • Imports, exports, and some file extract operations return a task id; you must call the paired status endpoint for completion info (the operations expose explicit status endpoints that return URLs or results once done).

• Files: path vs id vs environment

  • Files can be manipulated by path within an environment (draft or published) or by fileId. When creating/updating CMS source files, include the environment in the path-based endpoints.

• Marketing events: external vs internal ids

  • Many operations accept externalEventId together with externalAccountId for the upstream system mapping. When in doubt, use the objectId endpoints when you already have HubSpot's internal id.

• Many app-scoped resources require numeric appId

  • Media bridge schemas, timeline templates, custom action definitions, and feature flags all require appId. If a user references an app resource by name, find the numeric id first.

• Revisions and drafts

  • Content (blogs, landing pages, site pages, marketing emails) has explicit draft and revision endpoints. To publish, push a draft live via dedicated push-live endpoints rather than patching the published resource directly.

• Property validations and groups

  • Property validation is detailed and typed by ruleType. When updating or creating properties, check the property groups and validation rules first to avoid creating properties that fail later usage.

Prioritized checklist for common user requests

Use this mental checklist to pick endpoints and parameters for typical requests.

• "Find a contact by email and update a field"

  1. Search contacts: POST /crm/v3/objects/contacts/search (query by email) → extract contactId.
  2. Patch contact: PATCH /crm/v3/objects/contacts/{contactId} (or idProperty=email) with the update body.

• "Add contacts X, Y to list L"

  1. Ensure list exists: GET /crm/v3/lists/{listId} (or create via POST /crm/v3/lists/_create).
  2. Add members: PUT /crm/v3/lists/{listId}/memberships/add_add or use batch upsert on contacts then add_add.

• "Create a new company and associate lead contacts"

  1. Create company: POST /crm/v3/objects/companies → companyId.
  2. Create or find contacts.
  3. Create associations: PUT /crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/{toObjectType}/{toObjectId} (or use batch association endpoint for multiple pairs).

• "Upload a file and give a signed URL"

  1. Upload: POST /files/v3/files_upload → fileId.
  2. Signed URL: GET /files/v3/files/{fileId}/signed-url_getSignedUrl with expirationSeconds.

• "Start an export and retrieve the download link"

  1. Start export: POST /crm/v3/exports/export/async_start → gets an exportId/task id.
  2. Poll: GET /crm/v3/exports/export/async/tasks/{taskId}/status_getStatus to receive the download uri when ready.

What to check in responses (practical cues)

• Search and batch responses often return paging tokens (paging.next.after) — use these tokens to request the next page if the user asked for more than the current page.
• Export/import/task responses return a task id; the paired status endpoint is the only way to get the final file URL or error details.
• Batch endpoints return per-item results; inspect these for partial failures rather than assuming the batch succeeded wholesale.
• When updating properties or schema, the API may return the created/updated schema — use that to validate the created fields.

When to prefer one endpoint family over another

• Use CRM v3 object endpoints for standard CRUD, search, and batch object operations.
• Use CRM v4 association endpoints when you need labeled associations or large association pages (v4 supports larger default limits and label-aware responses).
• Use the marketing and CMS-specific endpoints for marketing emails, campaigns, events, blogs, pages, and file/source-code operations — these resources have their own drafts, revisions, and publish flows.

Keep this mental model: find the ID you need (owner, objectId, listId, appId, campaignGuid, fileId), then call the domain endpoint that performs the action (object CRUD, association, list membership, file upload, publish/push-live). The API separates identity discovery (search, list, or schema endpoints) from the state-changing endpoints (create/patch/put/post/delete/archive), and many bulk operations exist to avoid repeated single-item calls.