Object Tags API (BETA) - HubSpot docs

Supported products

Scope requirements

Use the Object Tags API to create and manage object tags. Tags can be created for objects with pipelines and are added to records based on specific criteria. For example, a Large deal tag added to deals with an Amount value over $10,000. Learn more about creating object tags in HubSpot.

Create object tags

To create an object tag, make a POST request to /crm/object-tags/2026-09-beta/{objectTypeId}. Include the following in your request body:

Field	Description
`name`	The name shown on the tag in the HubSpot UI.
`color`	The color displayed on the tag in the HubSpot UI. Options include: `BLACK`, `GRAY` (default), `RED`, `RED_LIGHT`, `ORANGE`, `ORANGE_LIGHT`, `YELLOW`, `YELLOW_LIGHT`, `GREEN`, `GREEN_LIGHT`, `TEAL`, `TEAL_LIGHT`,`BLUE`, `BLUE_LIGHT`, `PINK`, `PINK_LIGHT`, `PURPLE`, `PURPLE_LIGHT`.
`filterBranch`	The filters that determine which records have the tag.
`description`	A text description of the tag.
`displayOrder`	The order in which the tag shows in the pipeline tags settings HubSpot UI.
`filterPipelineIds`	An array with the `pipelineId` values of pipelines the tag is used in. Leave empty to use the tag in all the object’s pipelines.

For example, to create a Large deal tag on deals with an Amount value over $10,000 in one of your pipelines, make a POST request to /crm/object-tags/2026-09-beta/0-3 with the following request body:

{
  "name": "Large deal",
  "color": "GREEN",
  "filterBranch": {
    "filterGroups": [
      {
        "filters": [
          {
            "propertyName": "amount",
            "operator": "GT",
            "value": "10000"
          }
        ]
      }
    ]
  },
  "description": "Deals worth more than $10,000",
  "filterPipelineIds": ["default"]
}

Once created, the response includes an id you can use to update or delete the tag via API.

Retrieve object tags

To retrieve details about an individual object tag, make a GET request to /crm/object-tags/2026-09-beta/{objectTypeId}/{tagId}.
To retrieve all object tags for an object, make a GET request to /crm/object-tags/2026-09-beta/{objectTypeId}.

For example, to retrieve a ticket tag with the id 12345, make a GET request to /crm/object-tags/2026-09-beta/0-5/12345. Your response would look similar to:

{
  "results": [
    {
      "id": "12345",
      "objectType": "0-5",
      "name": "High Risk",
      "color": "RED",
      "filterBranch": {
        "filterGroups": [
          {
            "filters": [
              {
                "propertyName": "hs_ticket_priority",
                "operator": "EQ",
                "value": "URGENT"
              }
            ]
          }
        ]
      },
      "description": "Urgent tickets that are high risk and should be prioritized.",
      "filterPipelineIds": [],
      "createdAt": "2026-06-15T00:00:00.000Z",
      "updatedAt": "2026-06-15T00:05:00.000Z",
      "displayorder": 0,
      "createdBy": 456,
      "lastModifiedBy": 789
    }
  ]
}

To retrieve records with object tags, use the objects API and filter by hs_tag_ids or the same criteria used by your tag.

Update object tags

Partially update object tag definitions

To update specific fields in an object tag’s definition, make a PATCH request to /crm/object-tags/2026-09-beta/{objectTypeId}/{tagId}. In your request body, include only the fields you want to set, update, or clear. If an array is present (e.g., filterPipelineIds), the inputted values fully replace the existing values. For example, to update the High Risk ticket tag (12345) color to orange, remove the description, and use it only in your default support pipeline, make a PATCH request to /crm/object-tags/2026-09-beta/0-5/12345. Your request body would look similar to:

{
  "color": "ORANGE",
  "description": null,
  "filterPipelineIds": ["0"]
}

Replace object tag definitions

To fully update an object tag’s definition, make a PUT request to /crm/object-tags/2026-09-beta/{objectTypeId}/{tagId}. Include all required fields in your request body. If you omit a field, it will be cleared or returned to the default. If an array is present (e.g., filterPipelineIds), the inputted values fully replace the existing values. If you want to only update specific fields, perform a partial update instead.

Delete object tags

To delete an object tag, make a DELETE request to /crm/object-tags/2026-09-beta/{objectTypeId}/{tagId}. You’ll receive a 204 No Content response upon successful deletion. The tag will be removed from any records that met the tag’s criteria.

​Create object tags

​Retrieve object tags

​Update object tags

​Partially update object tag definitions

​Replace object tag definitions

​Delete object tags