Properties schemas (BETA)

Scope requirements

Use the properties schemas API to create, read, and manage property metadata for CRM objects. With this API, property details available in other CRM APIs, such as options, validation rules, and access settings, are available in one place.

This API is used for creating and managing properties and their metadata (i.e., labels, options). To update property values for records (e.g., set a contact’s job title), use the object APIs.

This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback.

Create properties

To create a custom property, make a POST request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties. For example, your request body may look similar to:

{
  "name": "favorite_food",
  "label": "Favorite food",
  "type": "ENUMERATION",
  "fieldType": "SELECT",
  "groupName": "contactinformation",
  "description": "The contact's favorite food.",
  "options": [
    {
      "label": "Pizza",
      "value": "pizza",
      "displayOrder": 1
    },
    {
      "label": "Tacos",
      "value": "tacos",
      "displayOrder": 2
    }
  ]
}

You can set the following fields in the request body:

Field	Type	Description
`name` required	String	The internal name of the property.
`label` required	String	The name of the property as it appears in HubSpot.
`type` required	String	The underlying value type of the property.
`fieldType` required	String	How the property is displayed in HubSpot and on forms.
`groupName` required	String	The name of the property group the property belongs to.
`options`	Array	The selectable options for enumeration properties. Defaults to an empty array.
`optionDecorators`	Object	The visual presentation settings for enumeration options, including their decoration style and assigned colors.
`accessAllowlist`	Array	Entries that restrict which users or teams can view or edit the property. Defaults to an empty array.
`validationRules`	Array	Rules enforced on the property’s value. Defaults to an empty array.
`dataSensitivity`	String	The data sensitivity classification: `NONE`, `STANDARD`, or `HIGH`.
`defaultValue`	String	The value applied when a record is created without a value for the property.
`description`	String	A description of what the property represents.
`formField`	Boolean	Whether the property is available in forms.
`hasUniqueValue`	Boolean	Whether values must be unique across all records of the object type.
`dataEntryInstructions`	String	Guidance text shown to users when they enter a value.
`calculationFormula`	String	For calculation properties, the formula used to compute the value. Requires a `fieldType` of `CALCULATION_EQUATION`. Learn how to create calculation properties.
`rollupConfig`	Object	For rollup properties, how the value is aggregated from associated records. Requires a `fieldType` of `CALCULATION_ROLLUP`. Learn how to create rollup properties.
`syncConfig`	Object	For sync properties, how the value is synced from an associated record. Learn how to create sync properties.

The response includes the newly created property, with the default fields and any other fields you set in the request. A 400 error is returned for invalid input, such as a duplicate name, invalid option values, or an incompatible type and fieldType pairing.

Create a batch of properties

To create up to 100 properties in one request, make a POST request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/batch/create. In the request body, include an inputs array. For example, to create two properties, your request would look similar to:

{
  "inputs": [
    {
      "name": "favorite_food",
      "label": "Favorite food",
      "type": "STRING",
      "fieldType": "TEXT",
      "groupName": "contactinformation"
    },
    {
      "name": "favorite_color",
      "label": "Favorite color",
      "type": "STRING",
      "fieldType": "TEXT",
      "groupName": "contactinformation"
    }
  ]
}

The response includes one result for each input, in the same order as your request. Each result includes the default fields and any other fields you set for that input. A failure on one input does not prevent the others from being created. If some inputs fail, the response returns a 207 status code with the details for each failed item. An empty inputs array returns a 400 error.

Create calculation properties

Calculation properties compute their value from other properties on the same record. To create a calculation property, set the fieldType to CALCULATION_EQUATION and include your formula in the calculationFormulafield. For example, to create a deal property that calculates a probability-weighted amount, your request body would look similar to:

{
  "name": "weighted_amount",
  "label": "Sales Weighted amount",
  "type": "NUMBER",
  "fieldType": "CALCULATION_EQUATION",
  "groupName": "dealinformation",
  "calculationFormula": "amount * hs_deal_stage_probability"
}

Reference properties in your formula by their internal names. Learn more about the available operators and functions in the calculation formula reference. A 400 error is returned if the formula can’t be parsed or references a property that doesn’t exist.

Create rollup properties

Rollup properties aggregate values from the records associated with the current record. To create a rollup property, set the fieldType to CALCULATION_ROLLUP and include a rollupConfig object. For example, to create a contact property that sums the amount of all associated closed won deals, your request body would look similar to:

{
  "name": "total_closed_won_amount",
  "label": "Total closed won amount",
  "type": "NUMBER",
  "fieldType": "CALCULATION_ROLLUP",
  "groupName": "contactinformation",
  "rollupConfig": {
    "associatedRecordType": "0-3",
    "associatedRecordProperty": "amount",
    "associationSpec": {
      "category": "HUBSPOT_DEFINED",
      "typeId": "3"
    },
    "rollupType": "SUM",
    "conditionalFormula": "dealstage == \"closedwon\""
  }
}

In rollupConfig, associatedRecordType, associatedRecordProperty, associationSpec, and rollupType are required. conditionalFormula is optional and filters which associated records are included, using the same formula syntax as calculation properties. When omitted, all associated records are included. Learn more about the rollupConfig fields. The MIN, MAX, AVG, and SUM rollup types only work with number properties. A 400 error is returned if rollupConfig is included without a fieldType of CALCULATION_ROLLUP, or if the associationSpec doesn’t exist between the two object types.

Create sync properties

Sync properties copy a value from an associated record onto the current record. To create a sync property, include a syncConfig object and set type and fieldType to values to match the value being synced. For example, to create a contact property that syncs the amount of the contact’s most recently created deal, your request body would look similar to:

{
  "name": "latest_deal_amount",
  "label": "Latest deal amount",
  "type": "NUMBER",
  "fieldType": "NUMBER",
  "groupName": "contactinformation",
  "syncConfig": {
    "associatedRecordType": "0-3",
    "associatedRecordProperty": "amount",
    "associationSpec": {
      "category": "HUBSPOT_DEFINED",
      "typeId": "3"
    },
    "syncPreference": "MOST_RECENTLY_CREATED"
  }
}

In syncConfig, all fields are required. syncPreference determines which associated record the value is synced from: FIRST_CREATED, MOST_RECENTLY_CREATED, or SYNC_VALUE (the only record of a one-to-one association). Learn more about the syncConfig fields.

Retrieve properties

Retrieve a single property

To retrieve a property, make a GET request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/{propertyName}. For example, a GET request to /crm/schemas/2027-03-beta/objects/0-1/properties/favorite_food?fields=label&fields=options would return a response similar to the following:

{
  "category": "USER_DEFINED",
  "name": "favorite_food",
  "type": "ENUMERATION",
  "fieldType": "SELECT",
  "label": "Favorite food",
  "options": [
    {
      "label": "Pizza",
      "value": "pizza",
      "displayOrder": 1
    },
    {
      "label": "Tacos",
      "value": "tacos",
      "displayOrder": 2
    }
  ],
  "createdAt": "2027-03-01T12:00:00.000Z",
  "updatedAt": "2027-03-01T12:00:00.000Z",
  "archived": false
}

The response includes the requested property with the following default fields: category, name, type, fieldType, createdAt, updatedAt, and archived. To return additional fields, include the fields query parameters in your request. Learn more about the supported fields. A 404 error is returned if the property doesn’t exist for the object.

Retrieve all properties for an object

To retrieve a paginated list of properties for an object, make a GET request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties. The following query parameters are available:

Parameter	Description
`archived`	Whether to include archived properties or active ones. Defaults to `false`, which returns only active properties. Set the value to `true` to return only archived properties.
`after`	A pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.
`limit`	The maximum number of properties to return per page. Defaults to 25, with a maximum of 100.
`fields`	The additional fields to return for each property. Learn more about the supported fields.

The response includes a page of properties, along with a cursor for the next page when more results exist.

Retrieve a batch of properties

To retrieve multiple properties by name, make a POST request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/batch/read. For example, your request body may look similar to:

{
  "inputs": [
    {"name": "favorite_food"},
    {"name": "favorite_color"},
    {"name": "favorite_movie"}
  ]
}

The response includes one result for each requested property with the following default fields: category, name, type, fieldType, createdAt, updatedAt, and archived. To return additional fields, include the fields query parameters in your request. Learn more about the supported fields. Any name that doesn’t match a property returns a not-found error for that item, and the request returns a 207 status code. An empty inputs array returns a 400 error.

Retrieve options for an option source

Some enumeration properties derive their options dynamically instead of storing static options on the property. For these properties, the optionsSource field is set. The supported values are OWNER (for properties that reference owners), PERSONA, and CALL_DISPOSITION. To retrieve the options for an option source, make a GET request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/option-sources/{optionSource}. For example, a request to /crm/schemas/2027-03-beta/objects/0-1/properties/option-sources/OWNER returns all the options for an owner-referencing contact property. The following query parameters are available:

Parameter	Description
`after`	A pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.
`limit`	The maximum number of options to return per page. Defaults to 25, maximum 100. Must be a positive number.

The response includes a page of options, along with a cursor for the next page when more results exist. A 400 error is returned for an invalid limit or after value, and a 404 error is returned if the option source doesn’t exist.

Update properties

To update a property, make a PATCH request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/{propertyName}. In the request body, include only the fields that you want to update. Omitted fields are left unchanged. For example, the following request body updates a property’s label and description:

{
  "label": "Favorite meal",
  "description": "The contact's favorite meal."
}

To change a rollup or sync property’s configuration, include an updated rollupConfig or syncConfig object. The object replaces the existing configuration rather than appending it, so you should include every field you want to keep. When you update a field that holds an array (e.g., options or validationRules), the array you send replaces the existing value rather than appending to it. For example, the following request body replaces any existing validation rules on the property with a single MAX_LENGTH rule:

{
  "validationRules": [
    {
      "ruleType": "MAX_LENGTH",
      "ruleArguments": ["100"]
    }
  ]
}

The response includes the property after the update, with the default fields and any other fields you changed in the request. A 404 error is returned if the property doesn’t exist, and a 400 error is returned for an invalid update, such as an incompatible type and fieldType change or a change to a field that cannot be modified for that property.

Update a batch of properties

To update up to 100 properties in one request, make a POST request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/batch/update. In the request body, include an inputs array, where each item names the property it applies to along with the fields to change. For example, to change one property’s label and another property’s description, your request body would look similar to:

{
  "inputs": [
    {
      "name": "favorite_food",
      "label": "Favorite meal"
    },
    {
      "name": "favorite_color",
      "description": "The contact's favorite color."
    }
  ]
}

The response includes one result for each input, in the same order as your request. Each result includes the default fields and any other fields you changed for that input. If some inputs fail, the response returns a 207 status code.

Archive and restore properties

You can archive a property, with the option to restore it later. The archived field on a property reflects its current state, and you can change it with a PATCH request.

To archive up to 100 properties in one request, make a POST request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/batch/archive.
To restore up to 100 archived properties, make a POST request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/batch/restore.

In both cases, include an inputs array of objects, each containing the internal property name in its name field. For example, your request body would look similar to:

{
  "inputs": [
    {"name": "favorite_food"},
    {"name": "favorite_color"}
  ]
}

A successful batch archive request returns 204 with no response body. A successful batch restore request returns 200 with the restored properties in the results array. If any inputs fail, the response returns 207 with per-item errors. For restore requests, successfully restored properties are included in results. Archive responses do not include successful items in results. An item fails with a 404 error if the property does not exist, or a 400 error if it’s already in the target state (i.e., already restored or archived).

Delete properties

Once you’ve archived a property, you can permanently delete it.

Please note: deleting a property is permanent and cannot be undone.

To delete a single property, make a DELETE request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/{propertyName}. A successful request returns no content. A 404 error is returned if the property doesn’t exist, and a 400 error is returned if the property hasn’t been archived.

Delete a batch of properties

To delete up to 100 properties in one request, make a POST request to /crm/schemas/2027-03-beta/objects/{objectTypeId}/properties/batch/purge. In the request body, include an inputs array of objects, each containing the internal property name in its name field. For example, your request body may look similar to:

{
  "inputs": [
    {"name": "favorite_food"},
    {"name": "favorite_color"}
  ]
}

A successful request returns a 204 with no body. If some inputs fail, the response returns a 207 status code with per-item errors.

Property fields reference

The following tables describe the fields included in property responses.

Field	Type	Description
`category`	String	Who defined the property: `HUBSPOT_DEFINED`, `INTEGRATION_DEFINED`, or `USER_DEFINED`.
`name`	String	The internal name of the property.
`label`	String	The display name shown in HubSpot.
`type`	String	The underlying value type of the property.
`fieldType`	String	How the property is displayed in HubSpot and on forms.
`description`	String	A description of what the property represents.
`options`	Array	For enumeration properties, the selectable options.
`optionDecorators`	Object	The visual presentation settings for enumeration options, including their decoration style and assigned colors.
`optionsSource`	String	Set when an enumeration property has dynamically derived options. `OWNER`, `PERSONA`, and `CALL_DISPOSITION` are supported values.
`calculated`	Boolean	Whether the property’s value is computed automatically instead of entered directly.
`calculationFormula`	String	The formula used to compute the value for calculation properties. Not returned if the property’s formula can’t be represented in this syntax.
`rollupConfig`	Object	For rollup properties, how the value is computed.
`syncConfig`	Object	For synced properties, how the value is synced from associated records.
`groupName`	String	The name of the property group the property belongs to.
`hidden`	Boolean	Whether the property is hidden from users in forms and the HubSpot UI. The property remains usable via API.
`readOnlyValue`	Boolean	Whether users can set the property’s value, or whether it’s system-managed.
`readOnlyDefinition`	Boolean	Whether the property’s definition can be edited, or is locked.
`readOnlyOptions`	Boolean	For enumeration properties, whether the set of options can be modified.
`hasUniqueValue`	Boolean	Whether values must be unique across all records of the object type.
`archivable`	Boolean	Whether the property can be archived.
`archived`	Boolean	Whether the property is currently archived.
`currencyPropertyName`	String	For number properties that represent a monetary amount, the name of the property that holds the currency code.
`dataEntryInstructions`	String	Guidance text shown to users when they enter a value.
`accessAllowlist`	Array	Entries that restrict which users or teams can view or edit the property.
`dataSensitivity`	String	The data sensitivity classification: `NONE`, `STANDARD`, or `HIGH`.
`sensitiveDataCategories`	Array	The categories of sensitive data the property may contain, either `HIPAA` or an empty array ([]).
`defaultValue`	String	The value applied when a record is created without a value for the property.
`formField`	Boolean	Whether the property is available in forms.
`validationRules`	Array	Rules enforced on the property’s value.
`dateDisplayFormat`	String	For date properties, how the value is displayed: `ABSOLUTE`, `ABSOLUTE_WITH_RELATIVE`, `TIME_SINCE`, or `TIME_UNTIL`.
`numberDisplayFormat`	String	For number properties, how the value is displayed: `UNFORMATTED`, `FORMATTED`, `CURRENCY`, `PERCENTAGE`, `DURATION`, or `PROBABILITY`.
`createdAt`	String	The timestamp of when the property was created.
`updatedAt`	String	The timestamp of when the property was last updated.
`createdByUserId`	String	The ID of the user who created the property.
`updatedByUserId`	String	The ID of the user who last updated the property.

Property type and fieldType values

When creating properties, both type and fieldType are required. The type value determines the underlying value type of the property, and the fieldType value determines how the property appears in HubSpot and on forms. A property’s type and fieldType combination must be compatible.

Please note: unlike the properties API, the properties schemas API uses uppercase values (e.g., STRING instead of string, and TEXT instead of text). URL and EMAIL are also separate fieldType values, rather than text with a textDisplayHint.

The following table lists the available type values and the fieldType values supported for each.

`type`	Supported `fieldType` values
`BOOL`	`BOOLEANCHECKBOX`, `CALCULATION_EQUATION`
`CURRENCY_NUMBER`	`NUMBER`
`DATE`	`DATE`
`DATETIME`	`DATE`
`ENUMERATION`	`BOOLEANCHECKBOX`, `CHECKBOX`, `RADIO`, `SELECT`, `CALCULATION_EQUATION`
`JSON`	`TEXT`
`NUMBER`	`NUMBER`, `CALCULATION_EQUATION`, `CALCULATION_READ_TIME`, `CALCULATION_ROLLUP`, `CALCULATION_SCORE`
`OBJECT_COORDINATES`	`TEXT`
`PHONE_NUMBER`	`PHONE_NUMBER`
`STRING`	`TEXT`, `TEXTAREA`, `EMAIL`, `URL`, `HTML`, `FILE`, `CALCULATION_EQUATION`
`TIME_RANGE`	`TEXT`

Options

Each item in the options array includes the following fields:

Field	Type	Description
`label`	String	The display label for the option.
`value`	String	The internal value stored when the option is selected.
`displayOrder`	Number	The position of the option when sorted by display order.
`hidden`	Boolean	Whether the option is hidden from end users in forms and meetings. The option still appears in the CRM and HubSpot UI.
`description`	String	A description of what the option represents.

Option decorators and colors

The optionDecorators object sets up the visual presentation settings for enumeration options, including their decoration style and assigned colors.

Field	Type	Description
`optionDecoratorStyle`	String	The visual style used to decorate enumeration options. Options are `LABEL_ONLY` (default), `LABEL_WITH_BADGE` (label is wrapped in a colored badge), or `LABEL_WITH_COLOR` (label is next to a colored dot).
`optionColors`	Array	The colors assigned to individual enumeration options. Each item contains `optionName` and `color`.

Each item in the optionColors array includes the following fields:

Field	Type	Description
`optionName`	String	The option value that the color applies to.
`color`	String	The color used to decorate the option in the UI. Available values are `BLACK`, `BLUE`, `BLUE_LIGHT`, `GRAY`, `GREEN`, `GREEN_LIGHT`, `ORANGE`, `ORANGE_LIGHT`, `PINK`, `PINK_LIGHT`, `PURPLE`, `PURPLE_LIGHT`, `RED`, `RED_LIGHT`, `TEAL`, `TEAL_LIGHT`, `YELLOW`, and `YELLOW_LIGHT`.

Rollup configuration

The rollupConfig object is present for rollup properties and includes the following fields:

Field	Type	Description
`associatedRecordType`	String	The object type ID of the associated records being aggregated.
`associatedRecordProperty`	String	The property on the associated records whose values are aggregated.
`associationSpec`	Object	The association between the property’s records and the associated records. Includes `category` (`HUBSPOT_DEFINED`, `USER_DEFINED`, or `INTEGRATOR_DEFINED`) and `typeId`.
`rollupType`	String	The aggregation applied: `MIN`, `MAX`, `AVG`, `COUNT`, `SUM`, `EARLIEST_DATE`, or `LATEST_DATE`.
`conditionalFormula`	String	An optional formula that filters which associated records are included in the aggregation.

Sync configuration

The syncConfig object is present for sync properties and includes the following fields:

Field	Type	Description
`associatedRecordType`	String	The object type ID of the associated records the value is synced from.
`associatedRecordProperty`	String	The property on the associated records that the value is synced from.
`associationSpec`	Object	The association between the property’s records and the associated records. Includes `category` (`HUBSPOT_DEFINED`, `USER_DEFINED`, or `INTEGRATOR_DEFINED`) and `typeId`. When creating a sync property, the `typeId` value must match the direction of source object to target object. The target object is the object for which you’re creating the property (e.g., creating a contact property (target) from a deal property (source), the `typeId` is `3` (deal to contact)). Refer to this list of default association type ID values.
`syncPreference`	String	Which record to sync from: `FIRST_CREATED`, `MOST_RECENTLY_CREATED`, or `SYNC_VALUE` (the only record of a one-to-one association).

Calculation formula reference

The calculationFormula field, and the conditionalFormula field in rollupConfig, use the same formula syntax.

Please note: this syntax differs from the formulas in the properties API. For example, conditionals are written as if(condition, value_if_true, value_if_false) instead of if ... then ... endif, and is_known replaces is_present.

Values and properties

Element	Syntax	Example
String	Text wrapped in single or double quotes.	`"closedwon"`, `'closedwon'`
Number	A whole or decimal number.	`1000`, `1.5`
Boolean	`true` or `false`.	`true`
Empty value	`null`.	`null`
Property	The property’s internal name. You don’t need to specify the property’s type.	`amount`

Operators

Operator	Type	Description	Example
`+`	Arithmetic	Adds two values.	`amount + bonus`
`-`	Arithmetic	Subtracts one value from another.	`amount - discount`
`*`	Arithmetic	Multiplies two values.	`amount * hs_deal_stage_probability`
`/`	Arithmetic	Divides one value by another.	`amount * (1 - discount_rate)`
`<`	Comparison	Less than.	`amount < 1000`
`>`	Comparison	Greater than.	`amount > 1000`
`<=`	Comparison	Less than or equal to.	`amount <= 1000`
`>=`	Comparison	Greater than or equal to.	`amount >= 1000`
`=`, `==`	Equality	Equal to.	`dealstage == "closedwon"`
`!=`	Equality	Not equal to.	`dealstage != "closedlost"`
`and`, `AND`, `&&`	Logical	True if both conditions are true. Mixed case (e.g., `And`) is not accepted.	`amount > 1000 AND dealstage == "closedwon"`
`or`, `OR`, `\|\|`	Logical	True if either condition is true. Mixed case is not accepted.	`dealstage == "closedwon" OR dealstage == "closedlost"`
`not`, `!`	Logical	Negates a condition. `!` is the unary form.	`not is_known(close_date)`

Use parentheses to control the order of arithmetic operations: amount * (1 - discount_rate).

Functions

Function names are case-sensitive.

Function	Returns	Description	Example
`abs(number)`	Number	Returns the absolute value of `number`.	`abs(-100)`
`add_time(base, amount, unit)`	Number	Adds `amount` of time to `base`. `unit` must be `"second"`, `"minute"`, `"hour"`, `"day"`, `"week"`, `"month"`, or `"year"`.	`add_time(createdate, 30, "day")`
`coalesce(value1, value2, ...)`	Matches the arguments	Returns the first argument that has a value. Accepts 2 to 100 arguments.	`coalesce(firstname, lastname)`
`concatenate(string1, string2, ...)`	String	Joins two or more strings together. Accepts up to 100 strings.	`concatenate(firstname, " ", lastname)`
`contains(text, substring)`	Boolean	Returns `true` if `text` contains `substring`. Case-sensitive.	`contains(dealname, "enterprise")`
`currency_decimal_places(currency)`	Number	Returns the number of decimal places used by `currency`.	`currency_decimal_places("USD")`
`dated_exchange_rate(currency, date)`	Number	Returns the exchange rate for `currency` on the given `date`.	`dated_exchange_rate("EUR", closedate)`
`euler()`	Number	Returns Euler’s number (e ≈ 2.71828).	`euler()`
`exchange_rate(currency)`	Number	Returns the current exchange rate for `currency`.	`exchange_rate("EUR")`
`if(condition, value_if_true[, value_if_false])`	Matches the arguments	Returns `value_if_true` if `condition` is true. Returns `value_if_false` if false; if omitted, returns `null`.	`if(amount > 1000, "large", "small")`
`ifs(condition1, value1, ...)`	Matches the arguments	Evaluates each condition in order and returns the value for the first true condition. Accepts up to 100 condition/value pairs.	`ifs(amount > 5000, "high", amount > 1000, "medium", amount > 0, "low")`
`is_known(property)`	Boolean	Returns `true` if `property` has a value.	`is_known(closedate)`
`last_updated(property)`	String	Returns the timestamp in milliseconds of when `property` was last updated.	`last_updated(amount)`
`lowercase(text)`	String	Converts `text` to lowercase.	`lowercase(dealname)`
`max(number1, number2)`	Number	Returns the larger of two numbers.	`max(amount, 500)`
`min(number1, number2)`	Number	Returns the smaller of two numbers.	`min(amount, 500)`
`month(date)`	Number	Returns the month of `date` as a number (1–12).	`month(closedate)`
`number_to_string(number)`	String	Converts `number` to a string.	`number_to_string(amount)`
`pipeline_probability(pipeline)`	Number	Returns the win probability of a pipeline stage.	`pipeline_probability(hs_pipeline_stage)`
`power(base, exponent)`	Number	Raises `base` to the power of `exponent`.	`power(2, 10)`
`round_down(number, decimal_places)`	Number	Rounds `number` down to `decimal_places` decimal places.	`round_down(4.353, 1)`
`round_nearest(number, decimal_places)`	Number	Rounds `number` to the nearest value at `decimal_places` decimal places.	`round_nearest(4.32, 1)`
`round_up(number, decimal_places)`	Number	Rounds `number` up to `decimal_places` decimal places.	`round_up(4.353, 1)`
`sqrt(number)`	Number	Returns the square root of `number`.	`sqrt(144)`
`starts_with(text, substring)`	Boolean	Returns `true` if `text` begins with `substring`. Case-sensitive.	`starts_with(dealname, "Enterprise")`
`string_length(text)`	Number	Returns the number of characters in `text`.	`string_length(dealname)`
`string_to_number(string)`	Number	Converts `string` to a number.	`string_to_number(revenue_string)`
`subtract_time(base, amount, unit)`	Number	Subtracts `amount` of time from `base`. `unit` must be `"second"`, `"minute"`, `"hour"`, `"day"`, `"week"`, `"month"`, or `"year"`.	`subtract_time(closedate, 30, "day")`
`time_between(date1, date2)`	Number	Returns the length of time between `date1` and `date2`.	`time_between(createdate, closedate)`
`time_between_exclude_weekends(date1, date2)`	Number	Returns the length of time between `date1` and `date2`, excluding weekends.	`time_between_exclude_weekends(createdate, closedate)`
`uppercase(text)`	String	Converts `text` to uppercase.	`uppercase(dealname)`
`year(date)`	Number	Returns the year of `date` as a number.	`year(closedate)`

Example formulas

To return a value based on a condition:

"calculationFormula": "if(amount > 1000, \"big\", \"small\")"

To use a fallback when a property is empty:

"calculationFormula": "coalesce(discount_amount, 0)"

To combine a conditional with other functions:

"calculationFormula": "if(is_known(close_date), round_up(amount * hs_deal_stage_probability), 0)"

Formula behavior

A 400 error is returned if a formula can’t be parsed, references a property that doesn’t exist, or passes invalid arguments to a function.
You can’t clear calculationFormula with a PATCH request. Calculation properties require a formula, so send a new formula to change it.
Some calculation properties, such as those created in HubSpot with functions that aren’t listed above, don’t return a calculationFormula. The calculated field is still true.

Access allowlist

Each item in the accessAllowlist array includes the following fields:

Field	Type	Description
`accessType`	String	The type of access: `VIEW` or `EDIT`.
`entityType`	String	The type of entity the entry applies to: `ALL`, `TEAM`, `USER`, or `ADMIN`.
`entityId`	String	The ID of the team or user the entry applies to. Not applicable when `entityType` is `ALL` or `ADMIN`.

Validation rules

Each item in the validationRules array includes the following fields:

Field	Type	Description
`ruleType`	String	The kind of validation applied. Options are listed in the table below.
`ruleArguments`	Array	The arguments for the rule, such as the maximum length or a regular expression pattern.
`shouldApplyNormalization`	Boolean	Whether to normalize the value before the rule is applied.

The following table lists the available ruleType values, the property type (and fieldType) each supports, and the ruleArguments each requires.

`ruleType`	Supported `type` (and `fieldType`)	Description and arguments
`AFTER_DATETIME_DURATION`	`DATETIME`	Require a duration after the current date and time. Argument: an ISO-8601 period, such as `["P1Y"]`.
`AFTER_DURATION`	`DATE`	Require a duration after the current date. Argument: an ISO-8601 period, such as `["P7D"]`.
`ALPHANUMERIC`	`STRING` (`TEXT` and `TEXTAREA`)	Restrict values to certain alphanumeric characters. Argument: one of `ALPHANUMERIC`, `ALPHA_ONLY`, or `NUMERIC_ONLY`.
`BEFORE_DATETIME_DURATION`	`DATETIME`	Require a duration before the current date and time. Argument: an ISO-8601 period, such as `["P1M"]`.
`BEFORE_DURATION`	`DATE`	Require a duration before the current date. Argument: an ISO-8601 period, such as `["P30D"]`.
`DAYS_OF_WEEK`	`DATE`, `DATETIME`	Restrict values to specific days. Argument: one to seven days by name, such as `["MONDAY", "WEDNESDAY", "FRIDAY"]`.
`DECIMAL`	`NUMBER`	Restrict the number of decimal places in values. Argument: an integer from 0 to 20, such as `["2"]`.
`DOMAIN`	`STRING` (`TEXT`)	Validate domain formatting. No arguments.
`EMAIL`	`STRING` (`TEXT` and `EMAIL`)	Validate email address formatting. No arguments.
`EMAIL_ALLOWED_DOMAINS`	`STRING` (`TEXT` and `EMAIL`)	Restrict values to specific email domains. Argument: one to 20 domain strings, such as `["company.com", "partner.com"]`.
`EMAIL_BLOCKED_DOMAINS`	`STRING` (`TEXT` and `EMAIL`)	Block specific email domains. Argument: one to 20 domain strings, such as `["competitor.com"]`.
`END_DATE`	`DATE`	Set a maximum date. Argument: a Unix timestamp in milliseconds, such as `["1640995200000"]`.
`END_DATETIME`	`DATETIME`	Set a maximum date and time. Argument: a Unix timestamp in milliseconds, such as `["1640995200000"]`.
`FORMAT`	`STRING` (`TEXT` and `TEXTAREA`)	Require specific text case formatting. Argument: one of `CAPITALIZATION`, `UPPER`, or `LOWER`.
`MAX_LENGTH`	`STRING` (`TEXT`, `TEXTAREA`, and `PHONE_NUMBER`)	Set a maximum character length. Argument: an integer from 1 to 10000, such as `["100"]`.
`MAX_NUMBER`	`NUMBER`	Set a maximum numeric value. Argument: a numeric value, such as `["1000"]`.
`MIN_LENGTH`	`STRING` (`TEXT`, `TEXTAREA`, and `PHONE_NUMBER`)	Set a minimum character length. Argument: an integer greater than 1, such as `["5"]`.
`MIN_NUMBER`	`NUMBER`	Set a minimum numeric value. Argument: a numeric value, such as `["0"]`.
`PHONE_NUMBER_WITH_EXPLICIT_COUNTRY_CODE`	`STRING` (`PHONE_NUMBER`)	Validate phone number formatting, with an option to validate by country code. Argument: none, or a lowercase two-letter country code, such as `["us"]`.
`REGEX`	`STRING` (`TEXT` and `TEXTAREA`)	Validate values with a custom regular expression. Arguments: a regex pattern (RE2 syntax) and an error message, such as `["^[A-Z]+$", "Must be uppercase"]`.
`SPECIAL_CHARACTERS`	`STRING` (`TEXT` and `TEXTAREA`)	Restrict special characters. Argument: `NOT_ALLOWED`.
`START_DATE`	`DATE`	Set a minimum date. Argument: a Unix timestamp in milliseconds, such as `["1640995200000"]`.
`START_DATETIME`	`DATETIME`	Set a minimum date and time. Argument: a Unix timestamp in milliseconds, such as `["1640995200000"]`.
`URL`	`STRING` (`TEXT` and `URL`)	Validate URL formatting. No arguments.
`URL_ALLOWED_DOMAINS`	`STRING` (`TEXT` and `URL`)	Restrict values to specific domains. Argument: one to 20 domain strings, such as `["hubspot.com", "example.com"]`.
`URL_BLOCKED_DOMAINS`	`STRING` (`TEXT` and `URL`)	Block specific domains. Argument: one to 20 domain strings, such as `["competitor.com"]`.
`WHITESPACE`	`STRING` (`TEXT` and `TEXTAREA`)	Restrict whitespace in values. Arguments for this rule are not documented.

Account & Settings

Automation

CMS

CRM

Marketing

Meetings

Querying data

Reporting

Revenue

Properties schemas (BETA)

Create properties

Create a batch of properties

Create calculation properties

Create rollup properties

Create sync properties

Retrieve properties

Retrieve a single property

Retrieve all properties for an object

Retrieve a batch of properties

Retrieve options for an option source

Update properties

Update a batch of properties

Archive and restore properties

Delete properties

Delete a batch of properties

Property fields reference

Property type and fieldType values

Options

Option decorators and colors

Rollup configuration

Sync configuration

Calculation formula reference

Values and properties

Operators

Functions

Example formulas

Formula behavior

Access allowlist

Validation rules

​Create properties

​Create a batch of properties

​Create calculation properties

​Create rollup properties

​Create sync properties

​Retrieve properties

​Retrieve a single property

​Retrieve all properties for an object

​Retrieve a batch of properties

​Retrieve options for an option source

​Update properties

​Update a batch of properties

​Archive and restore properties

​Delete properties

​Delete a batch of properties

​Property fields reference

​Property type and fieldType values

​Options

​Option decorators and colors

​Rollup configuration

​Sync configuration

​Calculation formula reference

​Values and properties

​Operators

​Functions

​Example formulas

​Formula behavior

​Access allowlist

​Validation rules

Create properties

Create a batch of properties

Create calculation properties

Create rollup properties

Create sync properties

Retrieve properties

Retrieve a single property

Retrieve all properties for an object

Retrieve a batch of properties

Retrieve options for an option source

Update properties

Update a batch of properties

Archive and restore properties

Delete properties

Delete a batch of properties

Property fields reference

Property type and fieldType values

Options

Option decorators and colors

Rollup configuration

Sync configuration

Calculation formula reference

Values and properties

Operators

Functions

Example formulas

Formula behavior

Access allowlist

Validation rules