HubSpot: Retrieve multiple custom object schemas in a batch request

← Schemas operations · Get started

Operation hubspot.schemas_batch_get_schemas

Provider route: POST /crm-object-schemas/2026-09/schemas/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["schemas"]["batchGetSchemas"]>[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.schemas.batchGetSchemas(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.schemas.batch_get_schemas(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	Model	Required within parent	Expand Retrieve multiple custom object schemas in a batch request — request body — body

Referenced models: Retrieve multiple custom object schemas in a batch request — 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
$	Model	Root	Expand Retrieve all custom object schemas — response body

Referenced models: Retrieve all custom object schemas — response body

Schemas

1 more schema is linked from the tables above, on the schema pages.

Retrieve multiple custom object schemas in a batch request — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
includeAssociationDefinitions	boolean	Required within parent	Indicates whether to include association definitions in the response.
includeAuditMetadata	boolean	Required within parent	Indicates whether to include audit metadata in the response.
includePropertyDefinitions	boolean	Required within parent	Indicates whether to include property definitions in the response.
inputs	array	Required within parent	An array of strings representing the identifiers of the object schemas to be read.
inputs[]	string	Each item

Retrieve all custom object schemas — response body

Field	Type	Presence	Description and constraints
$	object	Root
results	array	Required within parent	An array of object schemas, each represented by an ObjectSchema. This property contains the list of schemas returned by the API call.
results[]	Model	Each item	Expand Create a new custom object schema — response body

Referenced models: Create a new custom object schema — response body

Create a new custom object schema — response body

Field	Type	Presence	Description and constraints
$	object	Root
allowsSensitiveProperties	boolean	Required within parent	A boolean indicating whether the object schema allows sensitive properties.
archived	boolean	Required within parent	A boolean indicating whether the object schema is archived.
associations	array	Required within parent	Associations defined for a given object type.
associations[]	Model	Each item	Expand Create an association for a specified object type — response body
createdAt	string	Optional	When the object schema was created. Format: date-time
createdByUserId	JSON	Optional
createdByUserId (anyOf 1)	integer	Alternative	An integer representing the ID of the user who created the object schema. Format: int32
createdByUserId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
description	string	Optional	A string providing a description of the object schema.
fullyQualifiedName	string	Required within parent	An assigned unique ID for the object, including portal ID and object name.
id	string	Required within parent	A unique ID for this schema's object type. Will be defined as {meta-type}-{unique ID}.
labels	Model	Required within parent	Expand Create a new custom object schema — response body — labels
name	string	Required within parent	A unique name for the schema's object type.
objectTypeId	string	Required within parent	A string representing the type ID of the object.
primaryDisplayProperty	string	Optional	The name of the primary property for this object. This will be displayed as primary on the HubSpot record page for this object type.
properties	array	Required within parent	Properties defined for this object type.
properties[]	Model	Each item	Expand Create a new custom object schema — response body — properties item
requiredProperties	array	Required within parent	The names of properties that should be **required** when creating an object of this type.
requiredProperties[]	string	Each item
searchableProperties	array	Required within parent	Names of properties that will be indexed for this object type in by HubSpot's product search.
searchableProperties[]	string	Each item
secondaryDisplayProperties	array	Required within parent	The names of secondary properties for this object. These will be displayed as secondary on the HubSpot record page for this object type.
secondaryDisplayProperties[]	string	Each item
updatedAt	string	Optional	When the object schema was last updated. Format: date-time
updatedByUserId	JSON	Optional
updatedByUserId (anyOf 1)	integer	Alternative	An integer representing the ID of the user who last updated the object schema. Format: int32
updatedByUserId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Create an association for a specified object type — response body, Create a new custom object schema — response body — labels, Create a new custom object schema — response body — properties item

Create an association for a specified object type — response body

Field	Type	Presence	Description and constraints
$	object	Root	The definition of an association
createdAt	string	Optional	When the association was defined. Format: date-time
fromObjectTypeId	string	Required within parent	ID of the primary object type to link from.
id	string	Required within parent	A unique ID for this association.
name	string	Optional	A unique name for this association.
toObjectTypeId	string	Required within parent	ID of the target object type ID to link to.
updatedAt	string	Optional	When the association was last updated. Format: date-time

Create a new custom object schema — response body — labels

Field	Type	Presence	Description and constraints
$	object	Root
plural	string	Optional	The word for multiple objects. (There’s no way to change this later.)
singular	string	Optional	The word for one object. (There’s no way to change this later.)

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.

Create a new custom object schema — response body — properties item modification Metadata

Field	Type	Presence	Description and constraints
$	object	Root
archivable	boolean	Required within parent	Indicates whether the property can be archived.
readOnlyDefinition	boolean	Required within parent	Indicates whether the property's definition is read-only.
readOnlyOptions	boolean	Optional	Indicates whether the property's options are read-only.
readOnlyValue	boolean	Required within parent	Indicates whether the property's value is read-only.

Policy, approvals and errors

SDK function policy ID: hubspot.schemas_batch_get_schemas. Catalog operation: schemas_batch_get_schemas. 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.custom.highly_sensitive.read.v2", "crm.objects.custom.read", "crm.objects.custom.sensitive.read.v2", "crm.schemas.custom.read", "oauth"]

Official provider source