# Creating a new Custom Field

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.

Endpoint: POST /custom_fields
Version: 1.0.0

## Query parameters:

  - `include` (string)
    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.

## Request fields (application/json):

  - `custom_field` (object)

  - `custom_field.name` (string, required)
    The name of the new field.

  - `custom_field.value_type` (string, required)
    The format of the [custom field's value](/tag/Custom-Field-Values):
| Value Type           | Format                                   | Sample         |
| -------------------- |:----------------------------------------:| --------------:|
| string             | `                          |        "foo" |
| date               |                  | "2014-02-25" |
| number             |                         |           13 |
| currency           | [, ]| [998, "USD"] |
| single and multi | []                         |    [1, 2, 4] |

This is set to string` by default.

  - `custom_field.custom_field_set_id` (integer, required)
    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.

  - `custom_field.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.

  - `custom_field.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.

  - `custom_field.choices` (array)
    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.

  - `custom_field.choices.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.write_access` (string)
    The permission level required for a user to create, update, or delete a custom field's value.

  - `custom_field.read_access` (string)
    The read_access [permission setting on each custom field](https://mavenlink.zendesk.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://mavenlink.zendesk.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://mavenlink.zendesk.com/hc/en-us/articles/203041364):
  - account_collaboration
  - project_creator
  - project_lead
  - reports_viewer
  - reports_viewer_with_cost
  - account_admin (default).

## Response 200 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.id` (string)

  - `custom_fields` (object)

  - `external_references` (object)

  - `users` (object)

  - `custom_field_choices` (object)

  - `custom_field_sets` (object)

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)