---
title: "Create a new custom field"
method: POST
path: "/v0/custom_fields"
tags: ["Custom Fields"]
---

# Create a new custom field

`POST /v0/custom_fields`

## Request

- Base URL: `https://api.gem.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gem.com/v0/custom_fields`
- Auth: none declared

Returns the newly created custom field object.

De-duplication: If a custom field with the provided name already exists,
an error would be returned in the format of:
```
{
    "code": 400,
    "errors": {
        "json": {
            "custom_field": {
                "id": "example_custom_field_id",
                "is_hidden": false,
                "name": "multi_select",
                "options": [
                    {
                        "id": "example_option_id",
                        "is_hidden": false,
                        "value": "example_value"
                    },
                ],
                "project_id": "UHJvamVjdDox",
                "scope": "project",
                "value_type": "multi_select"
            }
        }
    },
    "message": "A custom field with the name already existed",
    "status": "Bad Request"
}
```

## Request body

- CustomFieldCreation
  - `name` string, required: The name of the custom field is unique in its scope. Any leading and trailing spaces of the name string will be removed.
  - `value_type` 'date' | 'text' | 'single_select' | 'multi_select', required: When `value_type` is `text`, `value` is a string. When `value_type` is `date`, `value` is a string of format `yyyy-mm-dd`. When `value_type` is `single_select`, `value` is a string of an option value. When `value_type` is `multi_select`, `value` is an array of strings of option values.
  - `scope` 'team' | 'project', required: Custom fields under `team` scope apply to all candidates. Custom fields under `project` scope apply to candidates in a specific project.
  - `project_id` string, ObjectID, nullable: Applicable and required when `scope` is `project`. If the custom field has `project` scope, this is the project ID that its associated with.
  - `option_values` string[]: Applicable and required when `value_type` is one of (`single_select`, `multi_select`).

## Response `201`

Created

- CustomField
  - `id` string, ObjectID
  - `created_at` integer
  - `name` string
  - `value_type` 'date' | 'text' | 'single_select' | 'multi_select': When `value_type` is `text`, `value` is a string. When `value_type` is `date`, `value` is a string of format `yyyy-mm-dd`. When `value_type` is `single_select`, `value` is a string of an option value. When `value_type` is `multi_select`, `value` is an array of strings of option values.
  - `scope` 'team' | 'project': Custom fields under `team` scope apply to all candidates. Custom fields under `project` scope apply to candidates in a specific project.
  - `project_id` string, ObjectID: If the custom field has `project` scope, this is the project ID that its associated with.
  - `is_hidden` boolean: `hidden` custom fields in the candidate info are not displayed in the Gem product or not returned when making a query on the Candidates endpoint.
  - `options` CustomFieldOption[]: Applicable when `value_type` is one of (`single_select`, `multi_select`).
    - `id` string, ObjectID
    - `value` string
    - `is_hidden` boolean: `hidden` options are not selectable in the Gem product. Candidate custom field values with `hidden` options are not returned when making a query to the Candidates endpoint.

## Other responses

- `422`: Unprocessable Content
- `default`: Default error response

---

[API](https://skmtc.dev/gem/apis/gem-crm-api.md) - [All operations](https://skmtc.dev/gem/apis/gem-crm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gem/apis/gem-crm-api/revisions/50a984e3c2b5?raw)