HubSpot: Retrieve the schema of a specified custom object

← Schemas operations · Get started

Operation hubspot.schemas_get_schema

Provider route: GET /crm-object-schemas/2026-09/schemas/{objectType}. 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"]["getSchema"]>[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.getSchema(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.get_schema(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.includeAssociationDefinitions	boolean	Optional	Default: true
query.includeAuditMetadata	boolean	Optional	Default: true
query.includePropertyDefinitions	boolean	Optional	Default: true

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 Create a new custom object schema — response body

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

Schemas

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

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.)

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

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	The formula used to calculate the value of this property, if it is a calculated property.
createdAt	string	Optional	When the property was created Format: date-time
createdUserId	string	Optional	The internal 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 property that defines the currency for this property, if applicable.
dataSensitivity	string	Optional	The sensitivity level of the data stored in this property, such as 'sensitive' or 'highly_sensitive'. Known values: highly_sensitive, non_sensitive, sensitive
dateDisplayHint	string	Optional	Controls how date properties are displayed in the HubSpot UI, with options such as 'absolute', 'absolute_with_relative', 'time_since', and '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	The order that this property should be displayed in the HubSpot UI relative to other properties for this object type. Properties are displayed in order starting with the lowest positive integer value. A value of -1 will cause the property to be displayed **after** any positive values. 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	Hidden options won't be shown in HubSpot.
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 Create a new custom object schema — response body — properties item 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 how number values should be displayed, with options like 'formatted' or 'currency'. 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 that describe the types of sensitive data contained in this property.
sensitiveDataCategories[]	string	Each item
showCurrencySymbol	boolean	Optional	Whether the property will display the currency symbol set in the account settings.
textDisplayHint	string	Optional	A hint for how text values should be displayed, with options like 'email' or 'phone_number'. 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	When the object type was last updated. 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, Create a new custom object schema — response body — properties item modification Metadata

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_get_schema. Catalog operation: schemas_get_schema. 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