Picklists and Global Picklists

Picklist values can be defined in three ways:

Embedded on create — the fastest path; supply a Picklists array on the EntityField payload.
Programmatic maintenance — the Picklist resource for adding, editing, reordering, or removing values after the field exists.
Global Picklist — bind a field to an existing shared value set so many fields reuse the same values.

Embedded Values on Create

Send a Picklists array with the field payload:

POST /api/3.0/entity/EntityField
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "EntityId": "7NS0000000000A50001",
  "Name": "Status",
  "Label": "Status",
  "FieldTypeId": "7NY0000000000090000",
  "PicklistSortAlphabetically": false,
  "Picklists": [
    { "Name": "Draft",      "Label": "Draft",      "Order": 0, "IsDefault": true, "Color": "#9CA3AF" },
    { "Name": "In Review",  "Label": "In Review",  "Order": 1, "Color": "#F59E0B" },
    { "Name": "Approved",   "Label": "Approved",   "Order": 2, "Color": "#10B981" },
    { "Name": "Active",     "Label": "Active",     "Order": 3, "ExternalValue": "ACT" },
    { "Name": "Expired",    "Label": "Expired",    "Order": 4 },
    { "Name": "Terminated", "Label": "Terminated", "Order": 5 }
  ]
}

Embedded values are cascaded on create only. To add, remove, or reorder values afterward, use the Picklist resource (below).

Field-level picklist properties

Property	Notes
`PicklistSortAlphabetically`	Sort by label alphabetically instead of by `Order`.
`NumberOfVisibleLines`	Required for MultiSelect. Sets the list-box height (must be > 0). Rejected on single-select Picklist.

Each Picklists entry

Property	Type	Notes
`Name`	string	Required. The stored value.
`Label`	string	Display text. Defaults to `Name`.
`Order`	int	0-based sort position. Non-negative.
`IsDefault`	bool	Marks the default value. At most one entry may set this.
`Color`	string	Hex badge color, `#RGB` or `#RRGGBB`.
`ExternalValue`	string	External key used when syncing to systems that identify picklist options by their own IDs (Dynamics CRM, HubSpot).

Validation

At least one value is required at create.
Duplicate Name values within a field are rejected (case-insensitive).
MultiSelect values cannot contain a semicolon (;) — it is the value separator on the wire.

Picklist Resource — Add / Edit / Remove Values

Each picklist option is a record in the Picklist entity. To manage values after a field exists, create/edit/delete Picklist records, setting ReferenceId to the owning EntityField's ID.

Add a value to an existing field

POST /api/3.0/entity/Picklist
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "ReferenceId": "7NX0000000000CB0001",
  "Name": "Renewed",
  "Label": "Renewed",
  "Order": 6,
  "Color": "#3B82F6"
}

Rename or recolor a value

PATCH /api/3.0/entity/Picklist/<picklist row id>
Authorization: Bearer <token>
Content-Type: application/json

{ "Label": "Renewed (Auto)", "Color": "#2563EB" }

Reorder values

Send a PATCH with the new Order on each value that moved. Order is a plain integer sort key — it does not have to be contiguous.

Delete a value

DELETE /api/3.0/entity/Picklist/<picklist row id>
Authorization: Bearer <token>

The last remaining value on a field cannot be deleted — delete the whole field instead. Any existing records that stored the removed value continue to display it, but new records can no longer select it.

Global Picklist

A Global Picklist field draws its values from a shared value set (a GlobalPicklistType) that already exists in your org — useful when the same values (countries, industries, tiers) are needed on many fields and should be maintained in one place. The shared value sets themselves are created and maintained by your administrator in Setup; through the API you bind a field to one that already exists.

Bind a field to an existing global picklist

Create a GlobalPicklist field (FieldTypeId7NY0000000000030000) and set PicklistTypeId to the ID of the existing shared value set:

POST /api/3.0/entity/EntityField

{
  "EntityId": "7NS0000000000A50001",
  "Name": "Country",
  "Label": "Country",
  "FieldTypeId": "7NY0000000000030000",
  "PicklistTypeId": "7O10000000000B10001",
  "DefaultValue": "Canada"
}

Obtain the target PicklistTypeId from the shared value set's page in Setup.

Constraints

PicklistTypeId is required for GlobalPicklist fields and must reference an existing shared value set.
A GlobalPicklist field must NOT include an embedded Picklists array — the bound value set is authoritative.
DefaultValue, if set, must exactly match one of the bound values.

Status Codes

HTTP	When
201 Created	Picklist value created.
404 Not Found	Missing permission on the Picklist resource.
406 Not Acceptable	Missing required property, duplicate `Name`, MultiSelect value contains `;`, or attempt to delete the last remaining value.

<< Field Type Reference | Lookup Filters >>

Table of Contents