Skip to content
Book a build

How do I create a property with the HubSpot API?

To create a property with the HubSpot API, send a POST to the properties endpoint for the object, such as /crm/properties/2026-03/contacts (or the older /crm/v3/properties/contacts), with name, label, type, fieldType and groupName. Dropdowns also need an options array with label, value, displayOrder and hidden. The credential needs the matching schema scope, such as crm.schemas.contacts.write.

On this page

What HubSpot supports natively

Detail (October 2026)
EndpointPOST /crm/properties/2026-03/{objectType} on https://api.hubapi.com; POST /crm/v3/properties/{objectType} still works
Required fieldsname, label, type, fieldType, groupName
Dropdown optionsoptions array; each option needs label, value, displayOrder and hidden
ScopeThe object’s schema write scope, for example crm.schemas.contacts.write or crm.schemas.deals.write
Unique IDsUp to 10 unique-value properties per object

Valid type and fieldType pairs:

typefieldType
stringtext, textarea, html, phonenumber, file, calculation_equation
numbernumber, calculation_equation
enumerationselect, radio, checkbox, booleancheckbox, calculation_equation
boolbooleancheckbox, calculation_equation
date / datetimedate

How to create a property with the HubSpot API

  1. Get a credential with the schema write scope for the object. See HubSpot private apps and scopes.
  2. Check the property doesn’t exist. GET the object’s properties and search by internal name and label, so you don’t create contract_type_2.
  3. Pick the group. Use an existing group’s internal name, such as companyinformation.
  4. Send the request. An example for a company dropdown:
{
"name": "contract_type",
"label": "Contract type",
"groupName": "companyinformation",
"type": "enumeration",
"fieldType": "select",
"options": [
{ "label": "Annual", "value": "annual", "displayOrder": 0, "hidden": false },
{ "label": "Monthly", "value": "monthly", "displayOrder": 1, "hidden": false }
]
}
  1. Store the option values, not the labels. Workflows, imports and API writes compare value.

Common mistakes

  • Labels as values. Changing a label later is harmless; changing a value breaks every filter and branch that uses it.
  • Different internal names across portals. If you run the same setup in several portals, the same field should have the same internal name and option values everywhere.
  • Hard-coding old paths. New integrations should use the latest date-based version; HubSpot releases one each March and September.

The API is the right tool for an integration that creates fields as part of its own setup. If you’re scripting properties to set up a portal, we recommend Jetstack AI Projects instead, which builds them from a brief with the workflows and pipelines that use them.

Where Jetstack AI fits

To set up new properties without scripting, use Projects: list the fields in a brief or upload a build spec (internal names, types and option values), approve the plan Jetty (the Projects assistant) writes, then approve deployment separately. Projects builds properties before the workflows that use them, and the receipt confirms each one by reading it back from HubSpot. It’s currently in limited release; see what Projects can build.

If the properties already exist in another portal, Jetstack’s Portal reuse copies them with their option values and reconciles them against what’s already in the destination, instead of you scripting each one. You can deploy the same setup to multiple destination portals, reviewing each portal’s mappings. For many new fields at once, see Jetstack’s Bulk Create Properties, which creates a property group and its properties in one task, and the developer overview.

Sources

Checked October 29, 2026. HubSpot changes its products often; tell us at team@jetstack.ai if something here is out of date.

API & developers

Do it from your own code or AI agent.

The Jetstack AI REST API, MCP server and CLI share API keys and scopes. Create and manage those keys in the app.

Read the developer docs

API & developers

Related questions.

How do I create a property with the HubSpot API?

To create a property with the HubSpot API, send a POST to the properties endpoint for the object, such as /crm/properties/2026-03/contacts (or the older /crm/v3/properties/contacts), with name, label, type, fieldType and groupName. Dropdowns also need an options array with label, value, displayOrder and hidden. The credential needs the matching schema scope, such as crm.schemas.contacts.write.

Can I create several HubSpot properties in one call?

HubSpot's properties API has batch endpoints alongside the single create. Batches keep you under the burst rate limit when you set up dozens of fields at once.

Can I change a property's type after creating it?

Change it with an update to the property, but check existing values first: switching a dropdown to a number, for example, affects records, workflows and reports that use it. Getting the internal name and type right at creation saves the trouble.

How many unique ID properties can an object have?

Up to ten per object. You create one by setting hasUniqueValue to true.