Retrieve Object Field Options API

Audience: Technical Builders, Implementors, and Developers

Purpose: Enables programmatic retrieval of field option metadata for Custom Object fields so integrations can safely validate values and align with the Object schema.

Overview

Use the Retrieve Object Field Options endpoint to programmatically retrieve the configured option values for selectable field types such as dropdowns, dynamic tags, radio buttons, and checkboxes.

This endpoint supports schema-aware integrations by allowing external systems to align with an Object’s current field configuration and validate allowed values before submitting Record updates. Because selectable options may vary across Objects or environments, retrieving them dynamically helps prevent invalid data submissions and hard-coded dependencies.

The material on this page builds on information covered in Objects Core Concepts and the Object Data Model.

Why Use this API?

Call this endpoint when your integration needs to understand which values are permitted for selectable fields. In most implementations, a direct call is unnecessary because field options are included in the /fields/ and /custom-objects/*/details responses. It is most useful when field options must be retrieved independently or when minimizing payload size is important.

Common scenarios include:

• Building dynamic UI components that reflect Object configuration

• Validating values before writing data to Records

• Supporting integrations across multiple businesses with different schemas

• Avoiding hard-coded option IDs or labels

• Synchronizing controlled vocabularies between systems

Because custom fields extend the default data model to store additional data, retrieving their configuration is often a prerequisite for reliable Record operations.

Retrieve Object Field Options API Behavior

Understanding how this endpoint behaves helps prevent common integration mistakes.

• This endpoint returns the configured option values for a specific field (for example, dropdown, radio, checkboxes, or dynamic tags) and does not return Record-level field values

• The request is scoped using object_pk and field_pk (UUIDs) and integrations typically retrieve or store these identifiers as part of Object and field discovery

• If include_entity_count=true, the response includes entity_count and becomes paginated, which is useful when you need to understand how widely an option is used

• Because selectable values are configuration-driven, retrieving options dynamically helps integrations adapt across businesses with different Object setups

---

Retrieve Object Field Options Endpoint

Want to try the API out? Visit our Swagger docs.

List field options

get

Lists field options for single or multi-select fields, such as dynamic tags, checkboxes, dropdown, radio, etc

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

field_pkstring · uuidRequired

object_pkstring · uuidRequired

Query parameters

include_entity_countbooleanOptional

Includes entity_count in response and makes the response paginated.

orderingstring · enumOptional

Which field to use when ordering the results. Prepend with '-' for descending order.

Possible values:

pageintegerOptional

A page number within the paginated result set.

page_sizeintegerOptional

Number of results to return per page.

searchstringOptional

A search term.

Responses

200Success

application/json

countintegerRequiredExample: 123

nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=4

previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=2

errorsone ofOptionalExample: ["error message"]

nullOptional

or

string[]Optional

get

/api/custom-objects/{object_pk}/fields/{field_pk}/options

HTTPcURLJavaScriptPython

GET /api/custom-objects/{object_pk}/fields/{field_pk}/options HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
Accept: */*

200Success

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "06fe6c54-ea50-469e-b7fd-898a6b1b51b2",
      "code": "",
      "name": "Option 1",
      "order": 1,
      "meta": {}
    }
  ],
  "errors": [
    "error message"
  ]
}

Retrieve Object Field Options Schemas

---

What's Next?

After retrieving field options via the API, you can:

• Retrieve Object and field metadata to understand schema structure.

• Create or update Records using validated option identifiers.

• Combine field options with metadata APIs to support dynamic, schema-aware integrations.

For more information on Objects, check out the following topics:

Related Topics

• Object APIs

• Object API Names

• Retrieve Object Details by ID API

• Search for Custom Object Fields