Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: 1.0.0
title: Kantata OX API Documentation Custom Field Choices API
description: Kantata OX's API provides access to the majority of Kantata OX's data model.
termsOfService: https://www.kantata.com/terms-of-use
contact:
name: Kantata OX Support
url: https://knowledge.kantata.com/hc/en-us
license:
name: COPYRIGHT © 2026 Kantata, Inc.
url: https://www.kantata.com/terms-of-use
x-logo:
url: https://theme.zdassets.com/theme_assets/56104/04e93064d309f75d054b8cee885d1ea51e9be8f7.png
backgroundColor: '#FFFFFF'
altText: Kantata OX API Documentation
href: https://developer.kantata.com
servers:
- url: https://api.mavenlink.com/api/v1
tags:
- name: Custom Field Choices
description: Custom Field Choices are possible values for `'single'` and `'multi'` type custom fields.
paths:
/custom_field_choices:
get:
summary: Fetching a list of Custom Field Choices
description: 'Returns all possible choices for all `''single''` and `''multi''` type custom fields on the requester''s account.
This endpoint returns structured Custom Field Choice objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `custom_field_choices` top-level JSON key.
Please see our Response Format section for more information.'
operationId: Get Custom Field Choices
tags:
- Custom Field Choices
parameters:
- in: query
name: active
description: Only return non-obsolete custom field choices.
schema:
type: boolean
- in: query
name: created_after
description: Filter for records created after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: created_before
description: Filter for records created before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: external_reference_external_message
description: Filter the objects based on the external message of their associated external references. This is an exact match.
schema:
type: string
- in: query
name: external_reference_external_status
description: Filter by the status of the external object in the external system.
schema:
type: string
- in: query
name: external_reference_service_model
description: Filter by the type of the external object this external reference belongs to.
schema:
type: string
- in: query
name: external_reference_service_model_ref
description: Filter by the id of the external object this external reference belongs to.
schema:
type: integer
format: int32
- in: query
name: external_reference_service_model_refs
description: Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs.
schema:
type: string
- in: query
name: external_reference_service_name
description: Filter by the name of the provider for integration.
schema:
type: string
- in: query
name: external_reference_status
description: Filter by the status of the integration, this can be successful or fail.
schema:
type: string
- in: query
name: for_choice_ids
description: Only return custom field choices for these specific custom field choice ids formatted '1,2,...'.
schema:
type: string
- in: query
name: for_custom_fields
description: Only return custom field choices for these specific custom field ids formatted '1,2,...'.
schema:
type: string
- in: query
name: has_external_references
description: Filter by whether or not the object has external references.
schema:
type: boolean
- in: query
name: include
description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `custom_field` (CustomField)
- `external_references` (ExternalReference) - Includes references to external integrations for this object.'
schema:
type: string
- in: query
name: matching
description: Includes custom field choices with a name that matches the search string.
schema:
type: string
- in: query
name: only
description: 'Allows you to request one or more resources directly by ID. Multiple IDs can be supplied
in a comma separated list, like `GET /api/v1/workspaces.json?only=5,6,7`.'
schema:
type: string
- in: query
name: order
description: 'Supply `order` with the name of a valid sort field for the endpoint and a direction.
Valid values: `label:asc`, `label:desc`, `position:asc`, and `position:desc`.'
schema:
type: string
default: position:asc
- in: query
name: page
schema:
type: integer
format: int32
default: 1
- in: query
name: per_custom_field
description: Evenly distribute the choices fetched by their custom_field_id in groups the size of the number specified.
schema:
type: integer
format: int32
- in: query
name: per_page
schema:
type: integer
format: int32
default: 20
maximum: 200
- in: query
name: updated_after
description: Filter for records updated after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: updated_before
description: Filter for records updated before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: without_external_reference_service_name
description: Exclude by the existence of an external reference with the specified service name.
schema:
type: string
responses:
'200':
description: A list of Custom Field Choices have been retrieved.
content:
application/json:
schema:
type: object
properties:
count:
type: integer
format: int32
meta:
type: object
properties:
count:
type: integer
format: int32
page_count:
type: integer
format: int32
page_number:
type: integer
format: int32
page_size:
type: integer
format: int32
results:
type: array
items:
type: object
properties:
key:
type: string
id:
type: string
custom_field_choices:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomFieldChoice'
external_references:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalReference'
custom_fields:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomField'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'403':
description: Forbidden request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'503':
description: Service is unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
components:
schemas:
ExternalReference:
title: External Reference
description: 'External References allows users see which objects (one of `Assignment`, `BillingMilestone`, `CustomField`, `CustomFieldChoice`, `CustomFieldSet`, `CustomFieldValue`, `Estimate`, `EstimateScenario`, `EstimateScenarioResource`, `Expense`, `ExpenseBudget`, `Invoice`, `Participation`, `Post`, `RateCard`, `Role`, `Skill`, `StatusReport`, `Story`, `StoryAllocationDay`, `Submission`, `SurveyAnswer`, `SurveyQuestion`, `SurveyResponse`, `SurveyTemplate`, `TimeEntry`, `TimeOffEntry`, `User`, `Vendor`, `Workspace`, `WorkspaceAllocation`, `WorkspaceGroup`, or `WorkspaceResource`
are synced with third party systems. This allows you to view the sync status of items in addition to the integration
specifics for a synced object.
Objects that are synced with a third party system have external integration
attributes that include the corresponding ID of the third party object with
which it is synced, a link that allows you to view the object in the third
party system, the status of the external object in the external system,
the status of the sync, and a link to exceptions.'
type: object
properties:
created_at:
type: string
format: date-time
description: The date and time the reference was created.
external_link:
type: string
description: A URL that links to either the external object or event.
external_message:
type: string
description: An optional message about the external object.
external_status:
type: string
description: The status of the external object in the external system.
last_synced_at:
type: string
format: date-time
locked:
type: boolean
description: 'An optional field, indicating whether the subject should be locked. To prevent changes to the
object in Kantata OX, set this to true. This currently only applies to expense report rejections.'
service_model:
type: string
description: The type of the external object to which this reference belongs.
service_model_ref:
type: string
description: The ID of the external object to which this reference belongs.
service_name:
type: string
description: The provider name of the integration.
status:
type: string
description: The status of the integration. Options are 'pending', 'successful', or 'failed'.
subject_id:
type: integer
format: int32
description: The ID of the Kantata OX object to which this external reference belongs.
subject_ref:
type: object
description: '`subject_ref` will only be included in the response if `subject` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
properties:
key:
type: string
id:
type: string
subject_type:
type: string
description: 'The type of Kantata OX object to which this external reference belongs.
One of `Assignment`, `BillingMilestone`, `CustomField`, `CustomFieldChoice`, `CustomFieldSet`, `CustomFieldValue`, `Estimate`, `EstimateScenario`, `EstimateScenarioResource`, `Expense`, `ExpenseBudget`, `Invoice`, `Participation`, `Post`, `RateCard`, `Role`, `Skill`, `StatusReport`, `Story`, `StoryAllocationDay`, `Submission`, `SurveyAnswer`, `SurveyQuestion`, `SurveyResponse`, `SurveyTemplate`, `TimeEntry`, `TimeOffEntry`, `User`, `Vendor`, `Workspace`, `WorkspaceAllocation`, `WorkspaceGroup`, or `WorkspaceResource`.'
updated_at:
type: string
format: date-time
description: The date and time the reference was last updated.
CustomField:
title: Custom Field
description: 'The [Custom Fields](https://mavenlink.zendesk.com/hc/en-us/articles/202924760-Custom-Fields-Overview-#arrange) object allows you to
view, create, update, and delete extra fields for additional Estimate, Project, Group, Resource, Task, and User information.
If Custom Fields represent the fields themselves, [Custom Field Values](/tag/Custom-Field-Values)
represent the values in/of those fields.'
type: object
properties:
choice_ids:
type: array
items:
type: string
description: '`choice_ids` will only be included in the response if `choices` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
created_at:
type: string
format: date-time
creator_id:
type: string
description: '`creator_id` will only be included in the response if `creator` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
custom_field_set_id:
type: string
description: '`custom_field_set_id` will only be included in the response if `custom_field_set` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
default_text:
type: string
description: 'The message in an empty custom field, before a `string`, `date`, `number`, or `currency` value is entered in.
This only appears in the UI.
Visible when whether the custom field is an input field..'
external_reference_ids:
type: array
items:
type: string
description: '`external_reference_ids` will only be included in the response if `external_references` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
name:
type: string
description: The name of the custom field.
read_access:
type: integer
format: int32
description: "The `read_access` [permission setting on each custom field](https://mavenlink.zendesk.com/hc/en-us/articles/202924760#see)\ndetermines the minimum permission needed to view a custom field and its value.\n* `Workspace` (Project), `Resource`, and `Story` (Task) custom fields are project-specific objects,\nso their minimum permissions are set at the [project level](https://mavenlink.zendesk.com/hc/en-us/articles/115002779293-Project-Permissions):\n - `project_collaboration` (default)\n - `time_logging`\n - `financial`\n - `project_admin`\n\nMost account-level permissions supercede project-level permissions. Therefore, Account Administrators\nare able to view all Project, Resource, and Task custom fields and values across the account,\nregardless of project participation or `read_access` settings.\n* `Estimate`, `WorkspaceGroup` (Group), and `User` custom fields are account-wide objects,\nso their minimum permissions are set at the [account level](https://mavenlink.zendesk.com/hc/en-us/articles/203041364):\n - `account_collaboration`\n - `project_creator`\n - `project_lead`\n - `reports_viewer`\n - `reports_viewer_with_cost`\n - `account_admin` (default)."
unique_constraint:
type: boolean
description: 'Indicates whether a custom field value must be unique across Estimates, Projects, Groups, Resources, Tasks, or Users.
This is set to `false` by default.
Does not apply to Custom Fields with choices.
Visible when whether the custom field is an input field..'
updated_at:
type: string
format: date-time
value_type:
type: string
description: "The format of the [custom field's value](/tag/Custom-Field-Values):\n | Value Type | Format | Sample |\n | -------------------- |:----------------------------------------:| --------------:|\n | `string` | `<text_string>` | `\"foo\"` |\n | `date` | `<ISO_8601 Date Format>` | `\"2014-02-25\"` |\n | `number` | `<integer_value>` | `13` |\n | `currency` | `[<int_value_in_cents>, <currency_code>]`| `[998, \"USD\"]` |\n | `single` and `multi` | `[<choice_ids>]` | `[1, 2, 4]` |\n\nThis is set to `string`, by default."
write_access:
type: integer
format: int32
description: The permission level required for a user to create, update, or delete a custom field's value.
Error:
type: object
properties:
type:
type: string
message:
type: string
CustomFieldChoice:
title: Custom Field Choice
description: Custom Field Choices are possible values for `single` and `multi` type custom fields.
type: object
properties:
created_at:
type: string
format: date-time
custom_field_id:
type: string
description: '`custom_field_id` will only be included in the response if `custom_field` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
external_reference_ids:
type: array
items:
type: string
description: '`external_reference_ids` will only be included in the response if `external_references` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
label:
type: string
position:
type: integer
format: int32
updated_at:
type: string
format: date-time
Errors:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
securitySchemes:
BearerToken:
type: apiKey
name: Bearer
in: header
OauthSecurity:
type: oauth2
flows:
authorizationCode:
scopes: {}
authorizationUrl: https://app.mavenlink.com/oauth/authorize
tokenUrl: https://app.mavenlink.com/oauth/token
x-tagGroups:
- name: '# Subscribed Events'
tags:
- Event Types
- Events
- name: Account Locations
tags:
- Account Locations
- name: Account Settings & Members
tags:
- Access Group Memberships
- Account Colors
- Account Invitations
- Account Memberships
- Backup Approver Associations
- Billable Utilizations
- Cost Rates
- Custom Branding
- Organization Memberships
- Organizations
- Roles
- Skill Categories
- Skill Memberships
- Skills
- Task Status Sets
- Task Statuses
- User Group Memberships
- Users
- name: Currencies
tags:
- Currencies
- name: Custom Fields
tags:
- Custom Field Choices
- Custom Field Sets
- Custom Field Values
- Custom Fields
- name: Data Exporter
tags:
- Data Export Schema
- Data Exports
- name: Estimates
tags:
- Estimate Scenario Resource Allocations
- Estimate Scenario Resources
- Estimate Scenarios
- Estimates
- name: Expense Budgets
tags:
- Expense Budgets
- name: Expense Tracking
tags:
- Attachments
- Expense Categories
- Expense Report Submissions
- Expenses
- Vendors
- name: External References
tags:
- External References
- name: Financials
tags:
- Billing Milestones
- Revenue Recognition Methods
- name: Foreign Exchange
tags:
- Exchange Tables
- name: Insights & Analytics
tags:
- Insights Access Group Memberships
- Insights Dynamic Dashboards
- Insights Report Exports
- Insights Reports
- name: Invoices
tags:
- Client Invoice Defaults
- External Payments
- Invoices
- Workspace Invoice Preferences
- name: Personal Settings
tags:
- Users
- name: Posts & Replies
tags:
- Attachments
- Posts
- User File Associations
- name: Project Snapshots
tags:
- Project Snapshots
- name: Project Templates
tags:
- Project Template Additional Tabs
- Project Template Assignments
- Project Template Expense Budgets
- Project Templates
- name: Projects
tags:
- Participations
- Project Accounting Records
- Status Reports
- Workspace Allocations
- Workspace Baselines
- Workspace Groups
- Workspace Invoice Preferences
- Workspace Resource Skills
- Workspace Resources
- Workspace Status Changes
- Workspace Task Status Sets
- Workspaces
- name: Rate Cards
tags:
- Activations
- Rate Card Role (Rate for a Role)
- Rate Card Set Version (Effective version by Date)
- Rate Card Sets (Group of Rate Cards)
- Rate Card Table Rows
- Rate Card Versions
- Rate Cards (Multiple Currencies)
- name: Recommendations
tags:
- Recommendations
- name: Resource Requests
tags:
- Resource Requests
- name: Scheduling
tags:
- Holiday Calendar Associations
- Holiday Calendar Memberships
- Holiday Calendars
- Holidays
- Time Off Entries
- Workweek Memberships
- Workweeks
- name: Surveys (Legacy)
tags:
- Survey Answers (Legacy)
- Survey Questions (Legacy)
- Survey Templates (Legacy)
- Surveys Responses (Legacy)
- name: Tasks
tags:
- Assignments
- Daily Scheduled Hours (Story Allocation Days)
- Followers
- Stories
- Story Dependencies
- Story State Changes
- Story Tasks
- name: Time Tracking
tags:
- Line Item Locks
- Time Entries
- Timesheet Approvals
- Timesheet Cancellations
- Timesheet Rejections
- Timesheet Submissions