HubSpot: Read a batch of properties

← Properties operations · Get started

Operation hubspot.properties_batch_get_properties

Provider route: POST /crm/properties/2026-09/{objectType}/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["properties"]["batchGetProperties"]>[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.properties.batchGetProperties(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.properties.batch_get_properties(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.objectType	string	Required within parent
query	object	Optional	Additional keys: not allowed
query.locale	string	Optional
body	Model	Required within parent	Expand Read a batch of properties — request body — body

Referenced models: Read a batch of properties — 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 Read a batch of properties — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Properties Batch Response Property
$ (anyOf 2)	Model	Alternative	Expand Read a batch of properties — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Properties Batch Response Property With Errors

Referenced models: Read a batch of properties — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Properties Batch Response Property, Read a batch of properties — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Properties Batch Response Property With Errors

Schemas

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

Read a batch of properties — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Properties Batch Response Property

Field	Type	Presence	Description and constraints
$	object	Root
completedAt	string	Required within parent	The timestamp indicating when the batch operation was completed. Format: date-time
links	object	Optional	A collection of URLs linking to documentation or resources related to the batch operation. Additional keys: see wildcard field
links.*	string	Additional keys
requestedAt	string	Optional	The timestamp indicating when the batch operation was requested. Format: date-time
results	array	Required within parent	An array of Property objects representing the results of the batch operation.
results[]	Model	Each item	Expand Read a property — response body
startedAt	string	Required within parent	The timestamp indicating when the batch operation began processing. Format: date-time
status	string	Required within parent	The current status of the batch operation, with possible values being CANCELED, COMPLETE, PENDING, or PROCESSING. Known values: CANCELED, COMPLETE, PENDING, PROCESSING

Referenced models: Read a property — response body

Read a batch of properties — response body — status: CANCELED, COMPLETE, PENDING, PROCESSING — Properties Batch Response Property 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 encountered during the batch operation, each represented by a StandardError object.
errors[]	Model	Each item	Expand Remove associations — response body — errors item
links	object	Optional	A map of link names to their associated URIs, providing additional information or actions related to the batch operation. Additional keys: see wildcard field
links.*	string	Additional keys
numErrors	JSON	Optional
numErrors (anyOf 1)	integer	Alternative	The number of errors encountered during the batch operation. 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 properties that were processed in the batch operation.
results[]	Model	Each item	Expand Read a property — response body
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, Read a property — response body

Read a batch of properties — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
archived	boolean	Required within parent	Specifies whether the property is archived.
dataSensitivity	string	Required within parent	Indicates the sensitivity level of the data, such as 'non_sensitive', 'sensitive', or 'highly_sensitive'. One of: highly_sensitive, non_sensitive, sensitive
inputs	array	Required within parent	An array of property names to be included in the batch read operation. Each item in the array is a reference to a PropertyName object.
inputs[]	Model	Each item	Expand Read a batch of properties — request body — body inputs item

Referenced models: Read a batch of properties — request body — body inputs item

Read a property — response body

Field	Type	Presence	Description and constraints
$	object	Root	A HubSpot property
archived	boolean	Optional	Whether or not the property is archived.
archivedAt	string	Optional	When the property was archived. Format: date-time
calculated	boolean	Optional	For default properties, true indicates that the property is calculated by a HubSpot process. It has no effect for custom properties.
calculationFormula	string	Optional	Represents a formula that is used to compute a calculated property.
createdAt	string	Optional	The timestamp when the property was created, in ISO 8601 format. Format: date-time
createdUserId	string	Optional	The internal user ID of the user who created the property in HubSpot. This field may not exist if the property was created outside of HubSpot.
currencyPropertyName	string	Optional	The name of the currency property associated with this property, if applicable.
dataSensitivity	string	Optional	The sensitivity level of the data. Valid values include 'non_sensitive', 'sensitive', and 'highly_sensitive'. Known values: highly_sensitive, non_sensitive, sensitive
dateDisplayHint	string	Optional	Indicates how date values should be displayed, with options such as 'absolute', 'absolute_with_relative', 'time_since', or 'time_until'. Known values: absolute, absolute_with_relative, time_since, time_until
description	string	Required within parent	A description of the property that will be shown as help text in HubSpot.
displayOrder	JSON	Optional
displayOrder (anyOf 1)	integer	Alternative	Properties are shown in order, starting with the lowest positive integer value. Format: int32
displayOrder (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
externalOptions	boolean	Optional	For default properties, true indicates that the options are stored externally to the property settings.
fieldType	string	Required within parent	Controls how the property appears in HubSpot.
formField	boolean	Optional	Whether or not the property can be used in a HubSpot form.
groupName	string	Required within parent	The name of the property group the property belongs to.
hasUniqueValue	boolean	Optional	Whether or not the property's value must be unique. Once set, this can't be changed.
hidden	boolean	Optional	Whether or not the property will be hidden from the HubSpot UI. It's recommended this be set to false for custom properties.
hubspotDefined	boolean	Optional	This will be true for default object properties built into HubSpot.
label	string	Required within parent	A human-readable property label that will be shown in HubSpot.
modificationMetadata	Model	Optional	Expand Read a property — response body — modification Metadata
name	string	Required within parent	The internal property name, which must be used when referencing the property via the API.
numberDisplayHint	string	Optional	A hint for displaying number properties. Valid values include 'unformatted', 'formatted', 'currency', 'percentage', 'duration', and 'probability'. Known values: currency, duration, formatted, percentage, probability, unformatted
options	array	Required within parent	A list of valid options for the property. This field is required for enumerated properties, but will be empty for other property types.
options[]	Model	Each item	Expand Read a property — response body — options item
referencedObjectType	string	Optional	If this property is related to other object(s), they'll be listed here.
sensitiveDataCategories	array	Optional	An array of categories indicating the sensitivity of the data contained in the property.
sensitiveDataCategories[]	string	Each item
showCurrencySymbol	boolean	Optional	Whether or not the property will display the currency symbol set in the account settings.
textDisplayHint	string	Optional	A hint for displaying text properties. Valid values include 'unformatted_single_line', 'multi_line', 'email', 'phone_number', 'domain_name', 'ip_address', 'physical_address', and 'postal_code'. Known values: domain_name, email, ip_address, multi_line, phone_number, physical_address, postal_code, unformatted_single_line
type	string	Required within parent	The property data type.
updatedAt	string	Optional	The timestamp when the property was last updated, in ISO 8601 format. Format: date-time
updatedUserId	string	Optional	The internal user ID of the user who updated the property in HubSpot. This field may not exist if the property was updated outside of HubSpot.

Referenced models: Read a property — response body — options item, Read a property — response body — modification Metadata

Read a batch of properties — request body — body inputs item

Field	Type	Presence	Description and constraints
$	object	Root
name	string	Required within parent	The name of the property to read or modify.

Read a property — response body — options item

Field	Type	Presence	Description and constraints
$	object	Root	A HubSpot property option
description	string	Optional	A description of the option.
displayOrder	JSON	Optional
displayOrder (anyOf 1)	integer	Alternative	Options are displayed in order starting with the lowest positive integer value. Values of -1 will cause the option to be displayed after any positive values. Format: int32
displayOrder (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
hidden	boolean	Required within parent	Hidden options will not be displayed in HubSpot.
label	string	Required within parent	A human-readable option label that will be shown in HubSpot.
value	string	Required within parent	The internal value of the option, which must be used when setting the property value through the API.

Policy, approvals and errors

SDK function policy ID: hubspot.properties_batch_get_properties. Catalog operation: properties_batch_get_properties. 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: ["automation", "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.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.feedback_submissions.read", "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.marketing_events.read", "crm.objects.marketing_events.write", "crm.objects.orders.read", "crm.objects.owners.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.pipelines.orders.read", "crm.schemas.appointments.read", "crm.schemas.carts.read", "crm.schemas.commercepayments.read", "crm.schemas.companies.read", "crm.schemas.contacts.read", "crm.schemas.courses.read", "crm.schemas.custom.read", "crm.schemas.deals.read", "crm.schemas.invoices.read", "crm.schemas.line_items.read", "crm.schemas.listings.read", "crm.schemas.orders.read", "crm.schemas.projects.read", "crm.schemas.quotes.read", "crm.schemas.services.read", "crm.schemas.subscriptions.read", "e-commerce", "media_bridge.read", "tickets", "tickets.highly_sensitive.v2", "tickets.sensitive.v2", "timeline"]

Official provider source