---
title: "HubSpot API: create a property (fields and scopes)"
description: "How to create a property with the HubSpot API: the endpoint, required fields, dropdown options, valid type and field type pairs, and the scope you need."
url: "https://jetstack.ai/answers/create-property-hubspot-api/"
---

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

![](https://jetstack.ai/images/authors/aditya-kumar.webp)

By [Aditya Kumar](https://jetstack.ai/authors/aditya-kumar/) Founder, Jetstack AI

Updated October 29, 2026

On this page

## What HubSpot supports natively

|                  | Detail (October 2026)                                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Endpoint         | `POST /crm/properties/2026-03/{objectType}` on `https://api.hubapi.com`; `POST /crm/v3/properties/{objectType}` still works |
| Required fields  | `name`, `label`, `type`, `fieldType`, `groupName`                                                                           |
| Dropdown options | `options` array; each option needs `label`, `value`, `displayOrder` and `hidden`                                            |
| Scope            | The object’s schema write scope, for example `crm.schemas.contacts.write` or `crm.schemas.deals.write`                      |
| Unique IDs       | Up to 10 unique-value properties per object                                                                                 |

Valid `type` and `fieldType` pairs:

| `type`              | `fieldType`                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| `string`            | `text`, `textarea`, `html`, `phonenumber`, `file`, `calculation_equation` |
| `number`            | `number`, `calculation_equation`                                          |
| `enumeration`       | `select`, `radio`, `checkbox`, `booleancheckbox`, `calculation_equation`  |
| `bool`              | `booleancheckbox`, `calculation_equation`                                 |
| `date` / `datetime` | `date`                                                                    |

## 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](https://jetstack.ai/answers/hubspot-private-app).
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  }
   ]
}
```

5. **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](https://jetstack.ai/build): 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](https://jetstack.ai/docs/projects/capabilities).

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](https://jetstack.ai/docs/implementations/bulk-properties/guide), which creates a property group and its properties in one task, and the [developer overview](https://jetstack.ai/docs/developers).

## Sources

- [Create a property, 2026-03 (HubSpot API reference)](https://developers.hubspot.com/docs/api-reference/2026-03/crm/properties/create-property)
- [CRM properties guide (HubSpot Developers)](https://developers.hubspot.com/docs/guides/api/crm/properties)
- [Introducing date-based API versioning (HubSpot Developer Changelog)](https://developers.hubspot.com/changelog/introducing-date-based-api-versioning)
- [Bulk properties (Jetstack AI documentation)](https://jetstack.ai/docs/implementations/bulk-properties/guide)

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

![Aditya Kumar](https://jetstack.ai/images/authors/aditya-kumar.webp)

About the author

[Aditya Kumar](https://jetstack.ai/authors/aditya-kumar/)

Founder, Jetstack AI

Aditya Kumar is the founder of Jetstack AI, the AI platform HubSpot partners and RevOps teams use to audit portals, build implementations and reuse their best setups across portals. He writes about HubSpot architecture, automation and AI from the work of building it.

[More from Aditya](https://jetstack.ai/authors/aditya-kumar/) [LinkedIn](https://www.linkedin.com/in/aditya-ambrstack/)

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](https://jetstack.ai/docs/developers)

On this page

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.
