---
title: "Creating a new Custom Field"
method: POST
path: "/custom_fields"
tags: ["Custom Fields"]
---

# Creating a new Custom Field

`POST /custom_fields`

## Request

- Base URL: `https://api.mavenlink.com/api/v1`
- URL: `https://api.mavenlink.com/api/v1/custom_fields`
- Auth: none declared

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/Response-Format) section for more information.

## Query parameters

- `include` string

## Request body

- object
  - `custom_field` object
    - `name` string, required: The name of the new field.
    - `value_type` string: 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` string: 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` boolean: 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` object[]: The list of [choices](/tag/Custom-Field-Choices) a user can select from for a custom field's value(s). A choice has two attributes, a `label` and an `ID`. Different choices can have the same `label`, but every choice will have a unique `ID`. For example, a request: ``` custom_field_choices: { .... choices: [ { "label": "Choice A" }, { "label": "Choice B" }, { "label": "Choice B" }, { "label": "Choice B" } ] .... } Will have a response like: ``` custom_field_choices: { .... choices: [ { "label": "Choice A", "id": "180291" }, { "label": "Choice B", "id": "180301" }, { "label": "Choice B", "id": "180311" }, { "label": "Choice B", "id": "180321" } ] .... } ``` Choices in the UI appear in the same order as listed in the array. Note that the 2nd, 3rd, and 4th choices all have the same label, but different IDs.
      - `label` string: 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` integer: 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` string: The permission level required for a user to create, update, or delete a custom field's value.
    - `read_access` string: The `read_access` [permission setting on each custom field](https://knowledge.kantata.com/hc/en-us/articles/202924760#see) determines the minimum permission needed to view a custom field and its value. * `Workspace` (Project), `Resource`, and `Story` (Task) custom fields are project-specific objects, so their minimum permissions are set at the [project level](https://knowledge.kantata.com/hc/en-us/articles/115002779293-Project-Permissions): - `project_collaboration` (default) - `time_logging` - `financial` - `project_admin` Most account-level permissions supercede project-level permissions. Therefore, Account Administrators are able to view all Project, Resource, and Task custom fields and values across the account, regardless of project participation or `read_access` settings. * `Estimate`, `WorkspaceGroup` (Group), and `User` custom fields are account-wide objects, so their minimum permissions are set at the [account level](https://knowledge.kantata.com/hc/en-us/articles/203041364): - `account_collaboration` - `project_creator` - `project_lead` - `reports_viewer` - `reports_viewer_with_cost` - `account_admin` (default).

## Response `200`

Custom Field has been created.

- object
  - `count` integer
  - `meta` object
    - `count` integer
    - `page_count` integer
    - `page_number` integer
    - `page_size` integer
  - `results` object[]
    - `key` string
    - `id` string
  - `custom_fields` object
  - `external_references` object
  - `users` object
  - `custom_field_choices` object
  - `custom_field_sets` object

## Other responses

- `400`: Bad Request
- `401`: Unauthorized request
- `403`: Forbidden request
- `404`: Page Not Found
- `422`: Unprocessable Entity
- `503`: Service is unavailable

---

[API](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation.md) - [All operations](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/revisions/9d4ebed2fa98?raw)