Skip to content

Create a new custom field definition

POST https://api.copper.com/developer_api/v1/custom_field_definitions

Field Type Details Default
name* string Name of the Custom Field Definition
data_type* string One of the following strings: "Checkbox", "Currency", “Date", "Dropdown", "Float", "MultiSelect", "Percentage", “String", "Text", "URL"
canonical_name string A unique string identifier for the Custom Field Definition, used in workflow automation rules. Presented as the "Field Key" via the Webapp. Will be automatically downcased on creation.
available_on string[] List of strings containing one or more of the following: “lead”, “person”, “opportunity”, “company”, "project", "task"
is_filterable boolean Indicates if the Custom Field Definition can be included in filters. Defaults to false if not provided.
options number[] Array of options for Dropdown and MultiSelect fields. A minimum of one option is required for Dropdown and a minimum of 2 options is required for MultiSelect
currency string 3-letter currency code (e.g., "USD","CAD")

* indicates a required field

Request Body

{
  "name": "A Dropdown",
  "canonical_name": "dropdown_field_1",
  "data_type": "Dropdown",
  "is_filterable": false,
  "available_on": [ "lead", "person", "company"],
  "options": [
    {
        "name": "Option1"
    },
    {
        "name": "Option2"
    }
  ]
}

Example Requests

Create a Dropdown Custom Field

curl --request POST "https://api.copper.com/developer_api/v1/custom_field_definitions" \
  --header "X-PW-AccessToken: YOUR_TOKEN_HERE" \
  --header "X-PW-Application: developer_api" \
  --header "X-PW-UserEmail: YOUR_EMAIL_HERE" \
  --header "Content-Type: application/json" \
  --data "{
  \"name\": \"A Dropdown\",
  \"canonical_name\": \"dropdown_field_1\",
  \"data_type\": \"Dropdown\",
  \"available_on\": [ \"lead\", \"person\", \"company\"],
  \"is_filterable\": false,
  \"options\": [
    {
        \"name\": \"Option1\"
    },
    {
        \"name\": \"Option2\"
    }
  ]
}"

{
    "id": 5,
    "name": "A Dropdown",
    "canonical_name": "dropdown_field_1",
    "data_type": "Dropdown",
    "available_on": [
        "lead",
        "person",
        "company"
    ],
    "is_filterable": false,
    "options": [
        {
            "id": 5,
            "name": "Option1",
            "rank": 0
        },
        {
            "id": 6,
            "name": "Option2",
            "rank": 1
        }
    ]
}

Create a Currency Custom Field

curl --request POST "https://api.copper.com/developer_api/v1/custom_field_definitions" \
  --header "X-PW-AccessToken: YOUR_TOKEN_HERE" \
  --header "X-PW-Application: developer_api" \
  --header "X-PW-UserEmail: YOUR_EMAIL_HERE" \
  --header "Content-Type: application/json" \
  --data "{
  \"name\": \"My Currency\",
  \"canonical_name\": \"dropdown_field_1\",
  \"data_type\": \"Currency\",
  \"available_on\": [ \"lead\", \"person\"],
  \"currency\": \"CAD\"
}"

{
    "id": 6,
    "name": "My Currency",
    "canonical_name": "dropdown_field_1",
    "data_type": "Currency",
    "available_on": [
        "lead",
        "person"
    ],
    "currency": "CAD"
}

Create a String Custom Field

curl --request POST "https://api.copper.com/developer_api/v1/custom_field_definitions" \
  --header "X-PW-AccessToken: YOUR_TOKEN_HERE" \
  --header "X-PW-Application: developer_api" \
  --header "X-PW-UserEmail: YOUR_EMAIL_HERE" \
  --header "Content-Type: application/json" \
  --data "{
  \"name\": \"A String\",
  \"canonical_name\": \"dropdown_field_1\",
  \"data_type\": \"String\",
  \"available_on\": [ \"lead\", \"person\"]
}"

{
    "id": 7,
    "name": "A String",
    "canonical_name": "dropdown_field_1",
    "data_type": "String",
    "available_on": [
        "lead",
        "person"
    ]
}