Updating custom fields on leads via API fails with 'Validation error' despite correct payload

CRM Zendesk Sell
, , , , , , , ,
1

We’re trying to update custom dropdown fields on leads through the REST API but consistently getting validation errors. The field is configured as a dropdown with specific values (New, Contacted, Qualified, Lost) but our API calls fail with ‘Invalid field value’ even when sending exact values from the field metadata.

Here’s our update request:

PUT /v2/leads/12345
{
  "custom_fields": {
    "lead_status_custom": "Qualified"
  }
}

The dropdown field metadata shows these exact values are valid. We’ve verified the field ID and tried both the display name and underlying value. This is blocking our lead enrichment workflow where we update 200+ leads daily from our qualification system. Has anyone encountered similar custom field mapping issues with the lead update endpoint?

2

I had this exact issue last month. The problem is that custom dropdown fields in Zendesk Sell use numeric IDs for their values, not the text labels. When you retrieve the field metadata via GET /v2/custom_fields/{field_id}, you’ll see a ‘choices’ array where each option has an ‘id’ and a ‘name’. You need to send the ID in your payload, not the name. Also make sure you’re using the correct field key - sometimes it’s ‘custom_fields.{field_name}’ and sometimes it’s just the field ID depending on how it was created. The API documentation isn’t super clear about this distinction between standard and custom field value handling.

3

Thanks for the pointer on value IDs. I checked the field metadata and you’re right - there are numeric IDs. But now I’m confused about the payload structure. Should I be sending the field ID as the key or the field name? And does the custom_fields wrapper change based on field type?

4

We ran into validation issues when our dropdown had special characters in the choice names. Even though the API returned those values in the metadata, sending them back would fail. We had to URL-encode some values. Also worth checking if your field has any validation rules or dependencies on other fields that might be triggering the error.

5

Double-check your field’s ‘editable_by_api’ property in the metadata response. Some custom fields are configured to be UI-only or have restricted API access based on user roles. If that property is false, you’ll get validation errors regardless of the payload format.