HubSpot: Create a new custom object schema

← Schemas operations · Get started

Operation hubspot.schemas_create_schema

Provider route: POST /crm-object-schemas/2026-09/schemas. 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"]["createSchema"]>[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.createSchema(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.create_schema(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 Create a new custom object schema — request body — body

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

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

Schemas

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

Create a new custom object schema — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
allowsSensitiveProperties	boolean	Required within parent	Determines if the object type can include properties that are marked as sensitive.
associatedObjects	array	Required within parent	Associations defined for this object type.
associatedObjects[]	string	Each item
description	string	Optional	A brief explanation of the object type.
labels	Model	Required within parent	Expand Create a new custom object schema — response body — labels
name	string	Required within parent	A unique name for this object. For internal use only.
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 — request body — 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
shouldCreateSameObjectAssociation	boolean	Required within parent	A boolean indicating whether associations should be created between objects of the same type.

Referenced models: Create a new custom object schema — request body — body properties item, Create a new custom object schema — response body — labels

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 a new custom object schema — request body — body properties item

Field	Type	Presence	Description and constraints
$	object	Root
description	string	Optional	A description of the property that will be shown as help text in HubSpot.
displayOrder	integer	Optional	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
externalOptionsReferenceType	string	Optional	Specifies the reference type for external options associated with the property.
fieldType	string	Required within parent	Controls how the property appears in HubSpot.
formField	boolean	Optional	Whether the property can be used in a HubSpot form.
groupName	string	Optional	The name of the group this 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.
label	string	Required within parent	A human-readable property label that will be shown in HubSpot.
name	string	Required within parent	The internal property name, which must be used when referencing the property from the API.
numberDisplayHint	string	Optional	Controls how numeric properties are formatted in the HubSpot UI One of: currency, duration, formatted, percentage, probability, unformatted
optionSortStrategy	string	Optional	Controls how the property options will be sorted in the HubSpot UI. One of: ALPHABETICAL, DISPLAY_ORDER
options	array	Optional	A list of available options for the property. This field is only required for enumerated properties.
options[]	Model	Each item	Expand Create a property — request body — body options item
referencedObjectType	string	Optional	Defines the options this property will return, e.g. OWNER would return name of users on the portal.
searchableInGlobalSearch	boolean	Optional	Allow users to search for information entered to this field (limited to 3 properties)
showCurrencySymbol	boolean	Optional	Whether the property will display the currency symbol in the HubSpot UI.
textDisplayHint	string	Optional	Controls how text properties are formatted in the HubSpot UI One of: domain_name, email, ip_address, multi_line, phone_number, physical_address, postal_code, unformatted_single_line
type	string	Required within parent	The data type of the property. One of: bool, date, datetime, enumeration, number, phone_number, string

Referenced models: Create a property — request body — body options item

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

Policy, approvals and errors

SDK function policy ID: hubspot.schemas_create_schema. Catalog operation: schemas_create_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.schemas.custom.write"]

Official provider source