HubSpot: Retrieve associations

← Associations operations · Get started

Operation hubspot.associations_batch_get_associations

Provider route: POST /crm/associations/2026-09/{fromObjectType}/{toObjectType}/batch/read. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/hubspot with npm, or alter-sdk-hubspot with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HubSpotIntegration } from "@alter-ai/hubspot";

async function execute(input: Parameters<HubSpotIntegration["associations"]["batchGetAssociations"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HubSpotIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.associations.batchGetAssociations(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_hubspot import HubSpotIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HubSpotIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.associations.batch_get_associations(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.fromObjectType	string	Required within parent
path.toObjectType	string	Required within parent
body	Model	Required within parent	Expand Retrieve associations — request body — body

Referenced models: Retrieve associations — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (anyOf 1)	Model	Alternative	Expand Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Association Multi With Label
$ (anyOf 2)	Model	Alternative	Expand Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Association Multi With Label With Errors

Referenced models: Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Association Multi With Label, Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Association Multi With Label With Errors

Schemas

3 more schemas are linked from the tables above, on the schema pages.

Retrieve associations — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
inputs	array	Required within parent	An array of PublicFetchAssociationsBatchRequest objects, each specifying the details for fetching associations for a particular object. This property is required.
inputs[]	Model	Each item	Expand Retrieve associations — request body — body inputs item

Referenced models: Retrieve associations — request body — body inputs item

Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Association Multi With Label

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The timestamp when the batch processing was completed, in ISO 8601 format. Format: date-time
links	object	Optional	An object containing relevant links related to the batch request. Additional keys: see wildcard field
links.*	string	Additional keys
requestedAt	string	Optional	The timestamp when the batch request was initially made, in ISO 8601 format. Format: date-time
results	array	Required within parent	An array of results from the batch operation, each representing an association with labels between objects.
results[]	Model	Each item	Expand Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item
startedAt	string	Required within parent	The timestamp when the batch processing began, in ISO 8601 format. Format: date-time
status	string	Required within parent	The status of the batch processing request: "PENDING", "PROCESSING", "CANCELED", or "COMPLETE". Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item

Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Batch Response Public Association Multi With Label With Errors

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The date and time when the batch operation was completed, in ISO 8601 format. Format: date-time
errors	array	Optional	An array of errors that occurred during the batch operation, with each error represented by a standard error object.
errors[]	Model	Each item	Expand Remove associations — response body — errors item
links	object	Optional	An object containing additional links related to the batch operation, with each link represented as a string. Additional keys: see wildcard field
links.*	string	Additional keys
numErrors	JSON	Optional
numErrors (anyOf 1)	integer	Alternative	The number of errors that occurred during the batch operation, represented as an integer. Format: int32
numErrors (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
requestedAt	string	Optional	The date and time when the batch operation was requested, in ISO 8601 format. Format: date-time
results	array	Required within parent	An array of results from the batch operation, each item representing a public association with labels.
results[]	Model	Each item	Expand Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item
startedAt	string	Required within parent	The date and time when the batch operation started, in ISO 8601 format. Format: date-time
status	string	Required within parent	The current status of the batch operation. Valid values include 'PENDING', 'PROCESSING', 'CANCELED', and 'COMPLETE'. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Remove associations — response body — errors item, Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item

Retrieve associations — request body — body inputs item

Field	Type	Presence	Description and constraints
$	object	Root
after	string	Optional	A paging cursor token used to retrieve the next set of results in a paginated response.
id	string	Required within parent	The unique identifier for the object whose associations are being fetched.

Retrieve associations — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING results item

Field	Type	Presence	Description and constraints
$	object	Root
from	Model	Required within parent	Expand Associate records (default) — response body — results item to
paging	Model	Optional	Expand Return all draft tables — response body — paging
to	array	Required within parent	An array of objects representing the target objects in the association. Each object includes the target object's ID and the types of associations, which are specified with labels.
to[]	Model	Each item	Expand Retrieve all associations by object type — response body — results item

Referenced models: Return all draft tables — response body — paging, Associate records (default) — response body — results item to, Retrieve all associations by object type — response body — results item

Remove associations — response body — errors item

Field	Type	Presence	Description and constraints
$	object	Root	Represents a standard error response in the HubSpot API, providing detailed information about an error that occurred during an API request.
category	string	Required within parent	The main category of the error.
context	object	Required within parent	Additional context-specific information related to the error. Additional keys: see wildcard field
context.*	array	Additional keys
context.*[]	string	Each item
errors	array	Required within parent	The detailed error objects.
errors[]	Model	Each item	Expand Batch insert events — response body — errors item errors item
id	string	Optional	A unique ID for the error instance.
links	object	Required within parent	URLs linking to documentation or resources associated with the error. Additional keys: see wildcard field
links.*	string	Additional keys
message	string	Required within parent	A human-readable string describing the error and possible remediation steps.
status	string	Required within parent	The HTTP status code associated with the error.
subCategory	object	Optional	A more specific error category within each main category.

Referenced models: Batch insert events — response body — errors item errors item

Return all draft tables — response body — paging

Field	Type	Presence	Description and constraints
$	object	Root	Represents the pagination information for navigating through a list of results in the API. It provides details on how to access the previous or next set of results.
next	Model	Optional	Expand Get all tax rates — response body — paging next
prev	Model	Optional	Expand Return all draft tables — response body — paging prev

Referenced models: Get all tax rates — response body — paging next, Return all draft tables — response body — paging prev

Associate records (default) — response body — results item to

Field	Type	Presence	Description and constraints
$	object	Root	Contains the Id of a Public Object
id	string	Required within parent	ID of the object

Retrieve all associations by object type — response body — results item

Field	Type	Presence	Description and constraints
$	object	Root	Represents an object that is associated with multiple other objects, with optional context.
associationTypes	array	Required within parent	An array of association types with labels, defining the nature of the associations between objects. Each item in the array is an AssociationSpecWithLabel object.
associationTypes[]	Model	Each item	Expand Retrieve all associations by object type — response body — results item association Types item
toObjectId	string	Required within parent	The unique identifier for the target object in the association.

Referenced models: Retrieve all associations by object type — response body — results item association Types item

Get all tax rates — response body — paging next

Field	Type	Presence	Description and constraints
$	object	Root	Specifies the paging information needed to retrieve the next set of results in a paginated API response
after	string	Required within parent	A paging cursor token for retrieving subsequent pages.
link	string	Optional	A URL that can be used to retrieve the next page results.

Policy, approvals and errors

SDK function policy ID: hubspot.associations_batch_get_associations. Catalog operation: associations_batch_get_associations. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["crm.objects.appointments.read", "crm.objects.appointments.sensitive.read.v2", "crm.objects.appointments.sensitive.write.v2", "crm.objects.appointments.write", "crm.objects.carts.read", "crm.objects.carts.write", "crm.objects.commercepayments.read", "crm.objects.commercepayments.write", "crm.objects.companies.highly_sensitive.read.v2", "crm.objects.companies.highly_sensitive.write.v2", "crm.objects.companies.read", "crm.objects.companies.sensitive.read.v2", "crm.objects.companies.sensitive.write.v2", "crm.objects.companies.write", "crm.objects.contacts.highly_sensitive.read.v2", "crm.objects.contacts.highly_sensitive.write.v2", "crm.objects.contacts.read", "crm.objects.contacts.sensitive.read.v2", "crm.objects.contacts.sensitive.write.v2", "crm.objects.contacts.write", "crm.objects.courses.read", "crm.objects.courses.write", "crm.objects.custom.highly_sensitive.read.v2", "crm.objects.custom.highly_sensitive.write.v2", "crm.objects.custom.read", "crm.objects.custom.sensitive.read.v2", "crm.objects.custom.sensitive.write.v2", "crm.objects.custom.write", "crm.objects.deals.highly_sensitive.read.v2", "crm.objects.deals.highly_sensitive.write.v2", "crm.objects.deals.read", "crm.objects.deals.sensitive.read.v2", "crm.objects.deals.sensitive.write.v2", "crm.objects.deals.write", "crm.objects.goals.read", "crm.objects.goals.write", "crm.objects.invoices.read", "crm.objects.invoices.write", "crm.objects.leads.read", "crm.objects.leads.write", "crm.objects.line_items.read", "crm.objects.line_items.write", "crm.objects.listings.read", "crm.objects.listings.write", "crm.objects.orders.read", "crm.objects.orders.write", "crm.objects.partner-clients.read", "crm.objects.partner-clients.write", "crm.objects.partner-services.read", "crm.objects.partner-services.write", "crm.objects.products.read", "crm.objects.products.write", "crm.objects.projects.highly_sensitive.read", "crm.objects.projects.highly_sensitive.write", "crm.objects.projects.read", "crm.objects.projects.sensitive.read", "crm.objects.projects.sensitive.write", "crm.objects.projects.write", "crm.objects.quotes.read", "crm.objects.quotes.write", "crm.objects.services.read", "crm.objects.services.write", "crm.objects.subscriptions.read", "crm.objects.subscriptions.write", "crm.objects.users.read", "crm.objects.users.write", "e-commerce", "media_bridge.read", "tickets", "tickets.highly_sensitive.v2", "tickets.sensitive.v2"]

Official provider source