How to Update Dropdown Property Options via HubSpot API

Updating dropdown (select-type) custom properties in HubSpot CRM via the API allows you to manage options dynamically, especially when integrating external systems. This guide walks you through the process step-by-step.

✅ Step 1: Get the Current Property

First, fetch the property definition to inspect its current options. For example, to fetch a contact property:

GET https://api.hubapi.com/crm/v3/properties/contacts/{propertyName}

This returns, among other fields, an options array that defines all possible dropdown values.

👉 Docs: HubSpot API Reference

✅ Step 2: Prepare the Updated List of Options

Next, construct a JSON body that contains all of the options you want the dropdown to include — both existing and new.

{
  "options": [
    {
      "label": "Option One",
      "value": "option_one",
      "displayOrder": 1,
      "hidden": false
    },
    {
      "label": "Option Two",
      "value": "option_two",
      "displayOrder": 2,
      "hidden": false
    },
    {
      "label": "New Option Three",
      "value": "new_option_three",
      "displayOrder": 3,
      "hidden": false
    }
  ]
}

💡 Tip: You must include all options you wish to keep. Any omitted options will be removed when you PATCH the property.

✅ Step 3: PATCH the Property to Update It

Use the PATCH endpoint to apply the update:

PATCH https://api.hubapi.com/crm/v3/properties/{objectType}/{propertyName}
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Body:

{
  "options": [
    { ... as above ... }
  ]
}

From the docs: “Perform a partial update of a property … Provided fields will be overwritten.”

⚠️ Important Caveats / Gotchas

When you PATCH with a new options array, it replaces the entire array. Include all options you want to keep.
There’s no append-only mode — you can’t just add one option without resending the entire list.
Ensure you’re using the correct objectType (e.g., contacts, companies, deals) and propertyName (the internal property name).
value must be unique; label is the display text shown in HubSpot.
For multi-select checkboxes, the process is similar, but the fieldType differs (e.g., checkbox).

🧪 Example in cURL

Here’s a complete example updating a contact property named my_custom_dropdown:

curl --request PATCH \
  --url https://api.hubapi.com/crm/v3/properties/contacts/my_custom_dropdown \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "My Custom Dropdown",
    "fieldType": "select",
    "type": "enumeration",
    "options": [
      {
        "label": "Existing Option A",
        "value": "opt_a",
        "displayOrder": 1,
        "hidden": false
      },
      {
        "label": "Existing Option B",
        "value": "opt_b",
        "displayOrder": 2,
        "hidden": false
      },
      {
        "label": "New Option C",
        "value": "opt_c",
        "displayOrder": 3,
        "hidden": false
      }
    ]
  }'

If successful, HubSpot returns a 200 OK response with the updated property metadata.

💬 Summary

| Step | Action | |------|---------| | 1 | Fetch the property definition | | 2 | Prepare all options (existing + new) | | 3 | PATCH the property with the full options array |

This ensures your dropdown field stays consistent and reflects your latest data structure — perfect for dynamic integrations or automation workflows.

📘 Resources:

HubSpot API Illustration