Properties

Use properties to store information on CRM records. HubSpot provides a set of default properties for each CRM object, and you can also create and manage your own custom properties either in HubSpot or using the properties API. 

When creating properties, it’s important to consider how to architect your data. In many cases, creating custom properties for HubSpot's standard objects is the right course of action. However, there may be times when you'll need to create a separate custom object with its own set of properties.

CRM objects are defined by a primary type and a set of properties. Each type has a unique set of standard properties, represented by a map of name-value pairs. 

Learn more about default properties for different objects:

• Contacts
• Companies
• Deals
• Tickets
• Activities (Calls, Emails, Meetings, Notes, Tasks)
• Leads(Sales Hub Professional and Enterprise)

Property groups are used to group related properties. Any grouped properties will appear next to each other on HubSpot records. If your integration creates any custom object properties, a custom property group will make it easy to identify that data.

When creating or updating properties, both type and fieldType values are required. The type value determines the type of the property, i.e. a string or a number. The fieldType property determines how the property will appear in HubSpot or on a form, i.e. as a plain text field, a dropdown menu, or a date picker.

In the table below, learn about the available property type and corresponding  fieldType values.

Valid values for fieldType include:

To create a property, make a POST request to /crm/v3/properties/{objectType}. In your request body, include the following required fields:

• groupName: the property group the property will be in.
• name: the internal name of the property (e.g., favorite_food).
• label: the name of the property as it appears in HubSpot (e.g., Favorite Food).
• type: the type of property.
• fieldType: the field type of the property.

For example, to create a contact property called Favorite Food, your request would look like:

When a record is created in HubSpot, a unique Record ID (hs_object_id) is automatically generated and should be treated as a string. These IDs are unique only within that object, so there can be both a contact and company with the same ID. For contacts and companies, there are additional unique identifiers, including a contact's email address (email) and a company's domain name (domain).

In some cases, you want may to create your own unique identifier property so that you can't enter the same value for multiple records. You can have up to ten unique ID properties per object. To create a property requiring unique values via API:

• Make a POST request to /crm/v3/properties/{objectType}.
• In your request body, for the hasUniqueValue field, set the value to true.

Once you've created your unique ID property, you can use it in an API call to retrieve specific records. The request URL could look like this: GET https://api.hubapi.com/crm/v3/objects/deals/abc?idProperty=system_a_unique. This will return the deal with the value of abc in the system_a_unique field.

You can then use this unique identifier property value to identify and update specific records in the same way you could use hs_object_id, email (contacts), or domain (companies).

Calculation properties define a property value based on other properties within the same object record. They are defined using a formula, which may include operations like min, max, count, sum, or average. You can use the properties API to read or create calculation properties in your HubSpot account, using a field type of calculation_equation and a type of number, bool, string, or enumeration.

You can define the property's calculation formula with the calculationFormula field.

Using calculationFormula, you can write your formula with arithmetic operators, comparison operators, logic operators, conditional statements, and other functions.

Literal syntax

• String literal: constant strings can be represented with either single quotes ('constant') or double quotes ("constant").
• Number literal: constant numbers can be any real numbers, and can include point notation. 1005 and 1.5589 are both valid constant numbers.
• Boolean literal: constant booleans can be true or false.

Property syntax

• String property variables: for an identifier string to be interpreted as a string property, it must be wrapped in the string function. For example, string(var1)will be interpreted as the value for the string property var1.
• Number property variables: all identifiers will be interpreted as number property variables.  For example, var1 will be interpreted as the value for the number property var1.
• Boolean property variables: for an identifier to be interpreted as a bool property, it must be wrapped in the bool function. For example, the identifier bool(var1) will be interpreted as the value for the boolean property var1.

Operators

Operators can be used with literal and property values. For arithmetic operators, you can use prefix notation to multiply, and parenthesis can be used to specify the order of operations.

Functions

The following are supported functions:

There are also two parsing functions:

• number_to_string: tries to convert the input number expression to a string.
• string_to_number: tries to convert the input string expression to a number.

For example, "Number of cars: " + num_cars is not a valid property because you can't add a string with a number, but "Number of cars: " + number_to_string(num_cars) is.

Conditional statements

You can also write your formula with conditional statements using if, elseif, endif, and else.

For example, a conditional statement could look like: if boolean_expression then statement [elseif expression then statement]* [else statement | endif] where the [a] brackets represent that a is optional, the a|b represent that either a or b will work, and * means 0 or more. endif can be used to finish a conditional statement prematurely, ensuring that the parser can identify which if the next elseif belongs to. 

Example formulas

The following are examples you can use to help define your own calculation formulas:

A more advanced example with conditionals:

You can retrieve information for individual properties or all properties within an object.

• To retrieve an individual property, make a GET request to crm/v3/properties/{object}/{propertyName}. For example, to retrieve the Favorite Food property, your request URL would be https://
  api.hubspot.com/crm/v3/properties/contacts/favorite_food.
• To retrieve all properties for an object, make a GET request to /crm/v3/properties/{objectType}.

To update a property value for a record, make a PATCH request to crm/v3/objects/{objectType}/{recordId}. In your request body, include the properties and their values in an array. Learn more about updating records via the object APIs.

When updating values for a record's checkbox type properties, format the values in the following ways:

• Boolean checkbox property: to display as Yes, or checked in HubSpot, your value must be true. To display as No or not checked in HubSpot, your value must be false.
• Multiple select checkbox property: to add or append values to a multiple checkboxes property, add a semicolon before the first value, and separate the values with semicolons without a space between. If the property has an existing value, the leading semicolon will append the values instead of overwriting the value. For example, a contact has the existing value DECISION_MAKER  for the hs_buying_role property. To add additional values without replacing the existing value, your request would look like this:

When assigning users to CRM records via API, your value must be user's owner id, which you can find in your property settings or via the owners API. For example, to assign a user as owner of a contact, send a PATCH request to crm/v3/objects/contacts/{contactId},  with the body { "properties":{ "hubspot_owner_id": "41629779"}}.

You can clear an object property value via the API by setting the property value to an empty string.

For example, to clear the firstname from a contact object, send a PATCH request to https://api.hubapi.com/crm/v3/objects/contacts/{contactId} with the body { "properties": { "firstname": ""}}.