---
title: "Creating a new Custom Field Value"
method: POST
path: "/custom_field_values"
tags: ["Custom Field Values"]
---

# Creating a new Custom Field Value

`POST /custom_field_values`

## Request

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

Creates a new value for the specified custom field. Creating a value can also override existing values,
effectively making this an update request as well.

When creating new [single or multi choice values](/tag/Custom-Field-Choices) that
override existing values, note that new values are not _added_ to existing values, but instead _replace_ existing values.
Additionally, every new value has a unique, new ID.

This endpoint has its own rate limit. See the [Knowledge Base](https://knowledge.kantata.com/hc/en-us/articles/9698066628123) for more information.

**Bulk Create or Update**

This endpoint supports bulk creating or updating up to 100 objects. In the request body, set the top-level key to its plural form and place the objects in an array. Example:

```
{
  "custom_field_values": [
    {
      "subject_type": "Workspace",
      "subject_id": 123,
      "custom_field_id": 456,
      "value": "Hello world"
    },
    {
      "subject_type": "Workspace",
      "subject_id": 123,
      "custom_field_id": 789,
      "value": "Hello world"
    }
  ]
}
```


This endpoint returns structured Custom Field Value 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_values` 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_value` object
    - `subject_type` string, required: You must specify which set of Custom Fields to return values for: * `Estimate` * `Story` (Task) * `User` * `Workspace` (Project) * `WorkspaceGroup` (Group) * `Resource` This parameter is required.
    - `subject_id` integer, required: The ID of the Estimate, Project, Group, Resource, Task, or User the custom field is for.
    - `custom_field_id` integer, required: The ID of the Custom Field to create or update the value for.
    - `value` string, required: The value to create or update to for the specified custom field. Values can be created or updated in these formats: | 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]` | ##### Note: The `write_access` [permission setting on each custom field](https://knowledge.kantata.com/hc/en-us/articles/202924760#see) determines the minimum permission needed to edit the value of each custom field. * Editing `Workspace` (Project), `Resource`, and `Story` (Task) custom fields are project-specific changes, so permissions are set at the project level: - `project_collaboration` - `time_logging` - `financial` - `project_admin` (default) Most account-level permissions supercede project-level permissions. Therefore, Account Administrators are able to edit all Project, Resource, and Task custom fields and values across the account, regardless of project participation or `write_access` settings. * Editing `Estimate`, `WorkspaceGroup` (Group), and `User` custom fields are account-wide changes, so permissions are set at the account level: - `account_collaboration` - `project_creator` - `project_lead` - `reports_viewer` - `reports_viewer_with_cost` - `account_admin` (default).

## Response `200`

Custom Field Value 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_field_values` object
  - `external_references` object
  - `custom_fields` object
  - `users` object
  - `custom_field_choices` object
  - `stories` object
  - `workspaces` object
  - `workspace_groups` 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)