There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Create a contact property

Last updated January 7, 2025

POST /properties/v1/contacts/properties

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing & CRM

Required Scope:

crm.schemas.contacts.write

This endpoint is used to create a custom property that can store a specific piece of data for contact records.

Use case for this endpoint: Let's say an integration needs to keep track of contacts' anniversaries. You can use this endpoint to create a custom date property for this information.

Example URL: https://api.hubapi.com/properties/v1/contacts/properties

Property types and field types

Properties have both a type (which controls how the data is treated) as well as a fieldtype (which controls how the property appears when used in a form). As an example, the fieldtypes radio, checkbox, and booleancheckbox appear as radio select, multi-select checkboxes, and single checkbox fields when used in a form, but they all use the (data) type of enumeration, since they all have a specific set options available for the value.

Response details

  • Returns a 200 with the data for the new property on success.
  • Returns a 409 Conflict error if there is already a property with the 'name' you used. Property names must be unique.
  • Returns a 400 error with more details in the response body if there is any other problem.
Required parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Name "name": {property name}
Used in the request body.		 The internal name of the property. The name is used to reference the property within the Contacts APIs. Each property must have a unique name.
Label "label": {property label}
Used in the request body.		 A human readable label for the property. The label is used to display the property inside the HubSpot app.
Property group "groupName": {property group name}
Used in the request body.		 The property group that the property belongs to. Properties are displayed by these groups inside HubSpot. See this page for more details about property groups.
Data type "type": {type}
Used in the request body.		 The data type that the property stores. Must be one of:
  • string - string data
  • number - number value, can be any positive or negative integer or decimal number
  • date - A specific date, stored as a millisecond Unix timestamp. See this page for more details about date and datetime properties
  • datetime - A specific time, stored as a millisecond Unix timestamp. See this page for more details about date and datetime properties
  • enumeration - one of a set of values that are set in the 'options' field. If this type is used, at least one option must be included.
Form field type "fieldType": {field type}
Used in the request body.		 Sets the way that the property appears when used as a form field. Must be one of:
  • textarea - a <textarea> field, stores data as a string
  • text - a simple text box, stores a string
  • date - a datepicker field, stores a date type
  • file - stores the URL location of a file. Note: The file itself must be stored separately, as the contact property cannot store the file, just the URL location of a file. Treated as a string.
  • number - a number input field, stores a number value
  • select - a dropdown box, uses the enumeration type
  • radio - a set of radio buttons, used with the enumeration data type.
  • checkbox - a set of checkboxes, used with the enumeration data type
  • booleancheckbox - a single checkbox, stores "true" (as a string) if checked.
Optional parameters How to use Description
Description "description": {property description}
Used in the request body.		 A description of the property. Will be displayed when viewing the property settings in HubSpot.
Enumerated options "options": {list of options}
Used in the request body.		 If the property is the enumeration type, you must include a list of options. These options will be the acceptable values for the property. Each option will have a value and a label. The value is the internal value, used to validate the property and used internally by the APIs. The label should be a human readable value, as the label is displayed in the HubSpot app.
Display order "displayOrder": {number value}
Used in the request body.		 Used to control the default order of the property within the property group. Properties will be displayed in ascending order, starting with 0. Defaults to -1; any contacts with -1 get displayed in the order they were created, after properties with positive values.
Use as form field "formField": {true or false}
Used in the request body.		 Controls whether or not the field will appear as an option when building a form in the HubSpot form builder.

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example POST URL: https://api.hubapi.com/properties/v1/contacts/properties The example below represents the JSON needed to create a single-line text property. Note the structure of the JSON that you must pass in required to pass, in order for the request to succeed: { "name": "newcustomproperty", "label": "A New Custom Property", "description": "A new property for you", "groupName": "contactinformation", "type": "string", "fieldType": "text", "formField": true, "displayOrder": 6, "options": [ ] } This example is for a multi-select checkboxes property, though any property with the type "enumeration" would have a similar format for the options: { "name": "multi_pick", "label": "multi pick", "description": "multi select picklist test", "groupName": "contactinformation", "type": "enumeration", "fieldType": "checkbox", "hidden": false, "options": [ { "label": "Option A", "value": "option_a" }, { "label": "Option B", "value": "option_b" }, { "label": "Option C", "value": "option_c" } ], "formField": true } If the request succeeds, you will get an HTTP 200 response with a JSON object, which represents the property that you've just created in the system. Here is the JSON response from the first example JSON above (as you can see, it's identical): { "name": "newcustomproperty", "label": "A New Custom Property", "description": "A new property for you", "groupName": "contactinformation", "type": "string", "fieldType": "text", "formField": true, "displayOrder": 6, "options": [ ] }