# Retrieve Object Field Options API

{% hint style="success" %}
**Audience:** Technical Builders, Implementors, and Developers

**Purpose:** Enables programmatic retrieval of field option metadata for <code class="expression">space.vars.object</code> fields so integrations can safely validate values and align with the <code class="expression">space.vars.object</code> schema.
{% endhint %}

## 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 <code class="expression">space.vars.object</code>’s current field configuration and validate allowed values before submitting <code class="expression">space.vars.entity</code> updates. Because selectable options may vary across <code class="expression">space.vars.objects</code> 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](/docs/concepts/objects/object-core-concepts.md) and the [Object Data Model](/docs/concepts/objects/object-data-model.md).

### 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 <code class="expression">space.vars.object</code> configuration
* Validating values before writing data to <code class="expression">space.vars.entities</code>
* Supporting integrations across multiple businesses with different schemas
* Avoiding hard-coded option IDs or labels
* Synchronizing controlled vocabularies between systems

Because <code class="expression">space.vars.fields</code> extend the default data model to store additional data, retrieving their configuration is often a prerequisite for reliable <code class="expression">space.vars.entity</code> 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 <code class="expression">space.vars.entity</code>-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 <code class="expression">space.vars.object</code> 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 <code class="expression">space.vars.object</code> setups

***

## Retrieve Object Field Options Endpoint

Want to try the API out? Visit our [Swagger](https://app.go.kizen.com/api/docs/public/swagger#/custom-objects/custom_objects_fields_options_list) docs.

## List field options

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

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"security":[{"businessId":[],"userId":[],"apiKey":[]}],"components":{"securitySchemes":{"businessId":{"type":"apiKey","in":"header","name":"X-BUSINESS-ID"}},"schemas":{"PaginatedFieldOptionList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/FieldOption"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"FieldOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"order":{"type":"integer"},"entity_count":{"type":"integer","nullable":true,"readOnly":true},"meta":{"type":"object","additionalProperties":{}},"percentage_chance_to_close":{"type":"integer","nullable":true,"description":"Stage's percentage chance to close, applicable only for stage field."},"status":{"nullable":true,"description":"Stage's status, applicable only for stage field.\n\n* `open` - open\n* `won` - won\n* `lost` - lost\n* `disqualified` - disqualified","oneOf":[{"$ref":"#/components/schemas/StatusEnum"},{"$ref":"#/components/schemas/NullEnum"}]}},"required":["entity_count","name"]},"StatusEnum":{"enum":["open","won","lost","disqualified"],"type":"string","description":"* `open` - open\n* `won` - won\n* `lost` - lost\n* `disqualified` - disqualified"},"NullEnum":{"enum":[null]}}},"paths":{"/api/custom-objects/{object_pk}/fields/{field_pk}/options":{"get":{"operationId":"custom_objects_fields_options_list","description":"Lists field options for single or multi-select fields, such as dynamic tags, checkboxes, dropdown, radio, etc","summary":"List field options","parameters":[{"in":"path","name":"field_pk","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"include_entity_count","schema":{"type":"boolean"},"description":"Includes entity_count in response and makes the response paginated."},{"in":"path","name":"object_pk","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"ordering","schema":{"type":"string","enum":["entity_count","name","order"]},"description":"Which field to use when ordering the results. Prepend with '-' for descending order."},{"name":"page","required":false,"in":"query","description":"A page number within the paginated result set.","schema":{"type":"integer"}},{"name":"page_size","required":false,"in":"query","description":"Number of results to return per page.","schema":{"type":"integer"}},{"name":"search","required":false,"in":"query","description":"A search term.","schema":{"type":"string"}}],"tags":["custom-objects"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedFieldOptionList"}}},"description":""}}}}}}
```

### Retrieve Object Field Options Schemas

## The PaginatedFieldOptionList object

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"PaginatedFieldOptionList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/FieldOption"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"FieldOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"order":{"type":"integer"},"entity_count":{"type":"integer","nullable":true,"readOnly":true},"meta":{"type":"object","additionalProperties":{}},"percentage_chance_to_close":{"type":"integer","nullable":true,"description":"Stage's percentage chance to close, applicable only for stage field."},"status":{"nullable":true,"description":"Stage's status, applicable only for stage field.\n\n* `open` - open\n* `won` - won\n* `lost` - lost\n* `disqualified` - disqualified","oneOf":[{"$ref":"#/components/schemas/StatusEnum"},{"$ref":"#/components/schemas/NullEnum"}]}},"required":["entity_count","name"]},"StatusEnum":{"enum":["open","won","lost","disqualified"],"type":"string","description":"* `open` - open\n* `won` - won\n* `lost` - lost\n* `disqualified` - disqualified"},"NullEnum":{"enum":[null]}}}}
```

***

## What's Next?

After retrieving field options via the API, you can:

* Retrieve <code class="expression">space.vars.object</code> and field metadata to understand schema structure.
* Create or update <code class="expression">space.vars.entities</code> using validated option identifiers.
* Combine field options with metadata APIs to support dynamic, schema-aware integrations.

For more information on <code class="expression">space.vars.objects</code>, check out the following topics:

<details>

<summary>Related Topics</summary>

* [Object APIs](/docs/concepts/objects/object-apis.md)
* [Object API Names](/docs/concepts/objects/object-apis/object-api-names.md)
* [Retrieve Object Details by ID API](/docs/concepts/objects/object-apis/retrieve-object-details-by-id-api.md)
* [Search for Object Fields](/docs/concepts/objects/custom-fields/custom-field-apis/search-object-fields-api.md)

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.kizen.com/docs/concepts/objects/custom-fields/custom-field-apis/retrieve-object-field-options-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.