HubSpot: Create a batch of properties

← Properties operations · Get started

Operation hubspot.properties_batch_create_properties

Provider route: POST /crm/properties/2026-09/{objectType}/batch/create. 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"]["batchCreateProperties"]>[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.batchCreateProperties(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_create_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
body	Model	Required within parent	Expand Create a batch of properties — request body — body

Referenced models: Create 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

5 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

Create a batch of properties — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
inputs	array	Required within parent	An array of PropertyCreate objects, each representing a property to be created. This field is required.
inputs[]	Model	Each item	Expand Create a property — request body — body

Referenced models: Create a property — request body — body

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

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

Policy, approvals and errors

SDK function policy ID: hubspot.properties_batch_create_properties. Catalog operation: properties_batch_create_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: ["crm.objects.carts.write", "crm.objects.orders.write", "crm.objects.users.write", "crm.pipelines.orders.write", "crm.schemas.appointments.write", "crm.schemas.carts.write", "crm.schemas.commercepayments.write", "crm.schemas.companies.write", "crm.schemas.contacts.write", "crm.schemas.courses.write", "crm.schemas.custom.write", "crm.schemas.deals.write", "crm.schemas.invoices.write", "crm.schemas.listings.write", "crm.schemas.orders.write", "crm.schemas.projects.write", "crm.schemas.quotes.write", "crm.schemas.services.write", "crm.schemas.subscriptions.write", "e-commerce", "tickets", "tickets.highly_sensitive.v2", "tickets.sensitive.v2"]

Official provider source