Create Custom Field

POST 
/custom-fields/

Create Custom Field.

info

Supports Custom Objects, Company (Business), and Project Management tasks (objectKey: "task", optional scopes). Contact and Opportunity fields continue to use the Locations custom-fields endpoints.

Request

Version stringrequired

API Version

Available optionsv3

application/json

application/json

Body

Bodyrequired

locationIdstringrequired

Location Id

namestring

Field name

descriptionstring

Description of the field

placeholderstring

Placeholder text for the field

showInFormsboolean

Whether the field should be shown in forms

optionsobject[]

Options for the field (Optional, valid only for SINGLE_OPTIONS, MULTIPLE_OPTIONS, RADIO, CHECKBOX, TEXTBOX_LIST type)

acceptedFormatsstring
Allowed file formats for uploads. Options include: .pdf, .docx, .doc, .jpg, .jpeg, .png, .gif, .csv, .xlsx, .xls, all
Available options.pdf.docx.doc.jpg.jpeg.png.gif.csv.xlsx.xlsall
dataTypestringrequired
Type of field that you are trying to create
Available optionsTEXTLARGE_TEXTNUMERICALPHONEMONETORYCHECKBOXSINGLE_OPTIONSMULTIPLE_OPTIONSDATETEXTBOX_LISTFILE_UPLOADRADIO
fieldKeystringrequired

Field key. For Custom Objects: custom_object.{objectKey}.{fieldKey}. For standard objects such as tasks: task.{fieldKey} (e.g. task.priority_n). When setting values via the Projects Tasks API, omit the task. prefix in customFields.

objectKeystringrequired

Object this field belongs to. Use task for Project Management task fields, or custom_object.{key} for custom objects (e.g. custom_object.pet).

isUniqueboolean

Whether the field should be unique within the object. Only applicable for custom objects with TEXT, LARGE_TEXT, NUMERICAL, and PHONE field types.

maxFileLimitnumber

Maximum file limit for uploads. Applicable only for fields with a data type of FILE_UPLOAD.

allowCustomOptionboolean

Determines if users can add a custom option value different from the predefined options in records for RADIO type fields. A custom value added in one record does not automatically become an option and will not appear as an option for other records.

parentIdstringrequired

ID of the parent folder

scopesobject[]

Optional visibility scopes for Project Management / task fields. Each entry limits the field to a space, folder, list, or workspace. Omit or pass [] for location-wide fields. Example: [{ "scopeType": "list", "scopeId": "<listId>" }].

Example (auto)

{
  "locationId": "ve9EPM428h8vShlRW1KT",
  "name": "Name",
  "description": "Pet name field",
  "placeholder": "Enter pet name",
  "showInForms": true,
  "options": [
    {
      "key": "option_a",
      "label": "Option A"
    }
  ],
  "acceptedFormats": [
    ".pdf",
    ".jpg"
  ],
  "dataType": "TEXT",
  "fieldKey": "task.my_field",
  "objectKey": "task",
  "isUnique": false,
  "maxFileLimit": 2,
  "allowCustomOption": true,
  "parentId": "3v34PM428h8vShlRW1KT",
  "scopes": [
    {
      "scopeType": "list",
      "scopeId": "6a102435124ecfb348bd5507"
    }
  ]
}

application/json

Successful response

application/json

Schema

Schema

fieldobject

The custom field or folder matching the requested id

Example (auto)

{
  "field": {
    "id": "661c06b4ffde146bdb469442",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "name": "Pet Name",
    "fieldKey": "custom_object.pet.name",
    "objectKey": "custom_object.pet",
    "dataType": "TEXT",
    "parentId": "3v34PM428h8vShlRW1KT",
    "showInForms": true,
    "dateAdded": "2025-01-02T09:35:39.032Z",
    "dateUpdated": "2025-01-02T09:35:39.032Z"
  }
}