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 Fields 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 Fields
description: 'The Custom Fields 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
represent the values in/of those fields.'
paths:
/custom_fields:
get:
summary: Fetching a list of Custom Fields
description: 'Returns all Custom Fields, unless filter parameters have been applied.
This endpoint returns structured Custom Field 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_fields` top-level JSON key.
Please see our Response Format section for more information.'
operationId: Get Custom Fields
tags:
- Custom Fields
parameters:
- 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: 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`.
- `choices` (CustomFieldChoice) - Includes the ID of a Custom Field''s choices.
- `creator` (User) - Includes the ID of a Custom Field''s creator.
- `custom_field_set` (CustomFieldSet) - Includes the ID of the Custom Field Set that a field belongs to.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.'
schema:
type: string
- in: query
name: matching
description: Filter by custom fields with a name similar to the specified 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: `name:asc`, `name:desc`, `updated_at:asc`, and `updated_at:desc`.'
schema:
type: string
default: name:asc
- in: query
name: page
schema:
type: integer
format: int32
default: 1
- in: query
name: per_page
schema:
type: integer
format: int32
default: 20
maximum: 200
- in: query
name: subject_type
description: 'Filters for the specified set of Custom Fields:
* `Estimate`
* `Story` (Task)
* `User`
* `Workspace` (Project)
* `WorkspaceGroup` (Group)
* `Resource`.'
schema:
type: string
- 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 Fields 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_fields:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomField'
external_references:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalReference'
users:
type: object
additionalProperties:
$ref: '#/components/schemas/User'
custom_field_choices:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomFieldChoice'
custom_field_sets:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomFieldSet'
'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'
post:
summary: Creating a new Custom Field
description: 'This endpoint returns structured Custom Field 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_fields` top-level JSON key.
Please see our Response Format section for more information.'
operationId: Create Custom Field
tags:
- Custom Fields
parameters:
- 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`.
- `choices` (CustomFieldChoice) - Includes the ID of a Custom Field''s choices.
- `creator` (User) - Includes the ID of a Custom Field''s creator.
- `custom_field_set` (CustomFieldSet) - Includes the ID of the Custom Field Set that a field belongs to.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.'
schema:
type: string
responses:
'200':
description: Custom Field has been created.
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_fields:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomField'
external_references:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalReference'
users:
type: object
additionalProperties:
$ref: '#/components/schemas/User'
custom_field_choices:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomFieldChoice'
custom_field_sets:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomFieldSet'
'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'
requestBody:
content:
application/json:
schema:
type: object
properties:
custom_field:
type: object
properties:
name:
type: string
description: The name of the new field.
value_type:
type: string
description: 'The format of the [custom field''s value](/tag/Custom-Field-Values):
| Value Type | Format | Sample |
| -------------------- |:----------------------------------------:| --------------:|
| `string` | `<text_string>` | `"foo"` |
| `date` | `<ISO_8601 Date Format>` | `"2014-02-25"` |
| `number` | `<integer_value>` | `13` |
| `currency` | `[<int_value_in_cents>, <currency_code>]`| `[998, "USD"]` |
| `single` and `multi` | `[<choice_ids>]` | `[1, 2, 4]` |
This is set to `string` by default.'
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.'
unique_constraint:
type: boolean
description: 'A boolean setting that requires a custom field value to be unique across Estimates, Projects, Groups,
Resources, Tasks, or Users.
This is set to `false` by default.'
choices:
type: array
description: "The list of [choices](/tag/Custom-Field-Choices) a user can select from\nfor a custom field's value(s). A choice has two attributes, a `label` and an `ID`. Different choices can have the\nsame `label`, but every choice will have a unique `ID`.\n\nFor example, a request:\n\n```\ncustom_field_choices: {\n ....\n choices: [\n { \"label\": \"Choice A\" },\n { \"label\": \"Choice B\" },\n { \"label\": \"Choice B\" },\n { \"label\": \"Choice B\" }\n ]\n ....\n}\n\nWill have a response like:\n\n```\ncustom_field_choices: {\n ....\n choices: [\n { \"label\": \"Choice A\", \"id\": \"180291\" },\n { \"label\": \"Choice B\", \"id\": \"180301\" },\n { \"label\": \"Choice B\", \"id\": \"180311\" },\n { \"label\": \"Choice B\", \"id\": \"180321\" }\n ]\n ....\n}\n```\n\nChoices in the UI appear in the same order as listed in the array.\n\nNote that the 2nd, 3rd, and 4th choices all have the same label, but different IDs."
items:
type: object
properties:
label:
type: string
description: 'You can think of a label as the actual value a user can select for the custom field.
*Note:* Different choices can have the same `label`.'
custom_field_set_id:
type: integer
format: int32
description: 'The ID of the [Custom Field Set](/tag/Custom-Field-Sets) that the field belongs to.
When a set ID is not specified, the field is added to a Project set titled ''Default Project Set''.
This means it becomes a Project field.'
write_access:
type: string
description: The permission level required for a user to create, update, or delete a custom field's value.
read_access:
type: string
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 are able to view\nall Project, Resource, and Task custom fields and values across the account, regardless of project participation or\n`read_access` settings.\n* `Estimate`, `WorkspaceGroup` (Group), and `User` custom fields are account-wide objects, so their minimum permissions\nare 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)."
required:
- name
required: true
/custom_fields/{id}:
put:
summary: Updating an existing Custom Field
description: 'Updates an existing custom field.
### Parameters that cannot be updated
Note that the `unique_constraint` and `value_type` parameters cannot be updated.
They are set during the process of creating a custom field.
### Updating choices
This endpoint also allows you to update the list of choices for a custom field with
single or multiple choices. For important details
regarding how this endpoint affects the list of available choices and how to avoid
creating duplicate choices, see the description of the `choice` body parameter.
This endpoint returns structured Custom Field 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_fields` top-level JSON key.
Please see our Response Format section for more information.'
operationId: Update Custom Field
tags:
- Custom Fields
parameters:
- in: path
name: id
required: true
description: The ID of the Model.
schema:
type: integer
- 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`.
- `choices` (CustomFieldChoice) - Includes the ID of a Custom Field''s choices.
- `creator` (User) - Includes the ID of a Custom Field''s creator.
- `custom_field_set` (CustomFieldSet) - Includes the ID of the Custom Field Set that a field belongs to.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.'
schema:
type: string
responses:
'200':
description: Custom Field has been updated.
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_fields:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomField'
external_references:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalReference'
users:
type: object
additionalProperties:
$ref: '#/components/schemas/User'
custom_field_choices:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomFieldChoice'
custom_field_sets:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomFieldSet'
'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'
requestBody:
content:
application/json:
schema:
type: object
properties:
custom_field:
type: object
properties:
name:
type: string
description: The name of the field.
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.'
choices:
type: array
description: "The list of [choices](/tag/Custom-Field-Choices) a user can select from,\nfor a custom field's value(s). Setting this field updates a custom field's\ncomplete list of choices; it behaves as an overwrite.\n**Include all existing choices in your request, whether you are updating their `label` or not.**\nAny choices not included in your request *will be deleted* from the custom field.\n\n**How to avoid creating duplicate choices**\n\nChoices have two attributes, a `label` and an `ID`. Different choices can have the same `label`,\nbut every choice has a unique `ID`. To properly update an existing choice within a list, you must specify the `ID`\nof the choice you want to change. If you do not, a new choice with a unique, new `ID` is created instead.\n\nFor example:\n\n```\ncustom_field_choices: {\n ....\n choices: [\n { \"label\": \"Choice A\", \"id\": \"180291\" },\n { \"label\": \"Choice B\", \"id\": \"180301\" },\n { \"label\": \"Choice C\" }\n ]\n ....\n}\n```\n\nChoices in the UI appear in the same order as listed in the array.\n\nThe 1st choice is an existing choice with an ID of `180291`, and is either staying or being updated to `Choice A`.\nThe 2nd choice is an existing choice with an ID of `180301`, and is either staying or being updated to `Choice B`.\nThe 3rd choice is a new choice to create, `Choice C`, and its unique ID will be returned in the response."
items:
type: object
properties:
label:
type: string
description: 'You can think of a label as the actual value a user can select for the custom field.
*Note:* Different choices can have the same `label`.'
id:
type: integer
format: int32
description: 'The unique ID of an existing choice(s). If you do not specify the `ID` of an existing choice in an update request,
a new choice with a unique, new `ID` is generated instead. Use this parameter to avoid replacing
existing choices with new ones.'
custom_field_set_id:
type: integer
format: int32
description: 'The ID of the [Custom Field Set](/tag/Custom-Field-Sets) that the field belongs to.
When a set ID is not specified, the field is added to a Project set titled ''Default Project Set''.
This means it becomes a Project field.'
write_access:
type: string
description: The permission level required for a user to create, update, or delete a custom field value for a subject.
read_access:
type: string
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)."
required: true
delete:
summary: Deleting an existing Custom Field
description: 'Deletes a custom field. Custom field values are deleted with their custom fields.
The response will contain no content and an HTTP 204 status code if the request was
successful, or a standard Kantata OX error message explaining why the object could not be deleted.'
operationId: Delete Custom Field
tags:
- Custom Fields
parameters:
- in: path
name: id
required: true
description: The ID of the Model.
schema:
type: integer
responses:
'204':
description: Custom Field has been deleted.
'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-t
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mavenlink/refs/heads/main/openapi/mavenlink-custom-fields-api-openapi.yml