custom_fields.segment is the field’s key,
not an opaque id, so your code reads the way the workspace talks. The key is
fixed at creation; renaming a field’s label in Sailer does not move it.
Values are typed. A number field returns a JSON number, a checkbox returns a
boolean, a date returns an ISO-8601 date string. They are not stringified.
Discovering the fields a workspace uses
GET /v1/fields lists every field defined on a resource, built-in and custom:
key, label, type, whether it is required or read-only, and allowed values for
selects. Pass entity=contact, entity=organization, or entity=deal to
restrict the list; omit it to list the whole workspace.
key it returns inside custom_fields on create and update. Guessing
from another workspace — or from these docs — is how you get an unknown-field
error.
On MCP, the same table is describe_schema. Call it first; clients cache tool
schemas by server, not by tenant, so custom fields are never on the tool itself.
Every custom field defined on the entity also appears on every record, with
null where a record has no value. Reading one record shows the keys in use,
but not their types or allowed values — that is what /v1/fields is for.
Writing them
Send only the keys you want to change. Unlisted fields are left alone:null. Sending an unknown key, or a value of the wrong
type, returns 422 with the offending key in error.detail.