Upcoming breaking change: Customer Agent Lead Status contact property becoming read-only

Developer Support Developer Announcements
1

We’re making the Customer Agent Lead Status contact propertyhs_customer_agent_lead_statussystem‑managed and read‑only. This property stores Customer Agent system-generated lead qualification status on contact records (e.g., whether a contact was qualified, partially qualified or not qualified).

What’s changing

Starting July 13, 2026 HubSpot will enforcehs_customer_agent_lead_status as a read-only contact property:

  • Only HubSpot-owned Customer Agent flows can update this field
  • External writes from public APIs, integrations, workflows or manual updates will no longer be allowed
  • Attempts to write to this property from outside Customer Agent will fail with an error

This change affects developers and integrations that:

  • Includehs_customer_agent_lead_statusin request bodies to CRM Objects APIs or set it via iPaaS tools (e.g., Make) or custom apps as part of your integration logic
  • Use this field as a general-purpose lead status or as part of non–Customer Agent automation

Note: Reading data from this property (e.g. in reports, lists or APIs) will continue to work. If you only consume this property as an output of Customer Agent for analytics or segmentation, no action is required.

What this means for developers

Before July 13, 2026:

  1. Audit your usage: Search your API payloads, app code, workflow actions and integration forhs_customer_agent_lead_status. Check any middleware that updates contact properties during lead flows.
  2. Redirect writing to the property: Create your own custom contact property for your integration’s lead status and update all API calls, workflows and integration configs to write to that property instead ofhs_customer_agent_lead_status. If you need to mirror Customer Agent’s status into your own property, you can do so by readinghs_customer_agent_lead_status and writing the value into your custom field.
  3. Test your changes: Confirm your integration no longer attempts to write tohs_customer_agent_lead_status and continues to function as expected.

Why is this changing?

Enforcing this property as read-only ensures that Customer Agent–driven lead qualification metrics accurately reflect product behavior from July 13, 2026 onward. In-app reporting and internal analytics usinghs_customer_agent_lead_status are no longer skewed by unrelated external writes. Future improvements to Customer Agent lead qualification and reporting can safely treat this field as a trusted system signal.

If you have any questions or comments, reply below to discuss this change.