Custom fields

Custom fields allow you to add additional data to your Pipedrive account that isn't included by default. Each deal, organization, person, and product item can contain custom fields. We have 16 different field types available, each with its own uses.

Creating a custom field

See our creating a new custom field tutorial to add a custom field programmatically.

MethodURLUseful for
POST/dealFieldsAdding a new deal field.
NB! Leads inherit all deals’ custom fields.
POST/organizationFieldsAdding a new organization field
POST/personFieldsAdding a new person field
POST/productFieldsAdding a new product field


Note that custom fields cannot be duplicated to multiple different Pipedrive accounts. You can add the custom fields with the same name and field type to different accounts but they'll have different values for key parameters referenced in our API.

Naming a custom field

All custom fields are referenced as randomly generated 40-character hashes in the dataset, for example, dcf558aac1ae4e8c4f849ba5e668430d8df9be12 - it may look like our office cat walked across the laptop, but this actually is a key for a custom field in our API dataset.


These 40-character custom fields (for example, dcf558aac1ae4e8c4f849ba5e668430d8df9be12) are not shown in our API Reference as they differ for each Pipedrive account, but they can be seen in the API requests and responses as well as used in the requests when adding new items or updating existing ones.

You can’t rename the reference of the custom field (the field API key), but you can rename the name of a custom field that’s visible to the User.

Inside Pipedrive, you can find the API key of a field by going to Settings > Data fields and choosing the entity (deal/person/organization/product). When you hover over the row of a custom field, a three-dot menu appears on the right-hand side. From there, choose Copy API key.

Finding the API key of a custom field

Finding the API key of a custom field

Referencing a custom field

Here’s how you use an example key for a custom field in an example POST request to /deals (make sure you replace the example key with yours before making the request):

$api_token = 'Your API token goes here';
$deal = array (
    'title' => 'New deal with a custom field',
    'value' => '500',
    'currency' => 'USD',
    'dcf558aac1ae4e8c4f849ba5e668430d8df9be12' => 'A new field value for an existing example custom field key'
$url = '' . $api_token;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $deal);
$output = curl_exec($ch);
$result = json_decode($output, true); // Check if an ID came back, if did print it out
if (!empty($result['data']['id'])) { echo 'Deal was added successfully!' . PHP_EOL; }

Each custom field type corresponds to a specific data format. To determine in which format you need to submit data into a custom field, make a GET request for the same kind of object and check the format of the value of that field. You can find the list of field_type in the table below.

Updating a custom field

See our updating custom fields’ values tutorial to update a custom field programmatically.

MethodURLUseful for
PUT/dealFields/{id}Updating a Deal field.
NB! Leads inherit all deal's custom fields.
PUT/organizationFields/{id}Updating an organization field
PUT/personFields/{id}Updating a person field
PUT/productFields/{id}Updating a product field

Deleting a custom field


We don't recommend deleting a custom field, because it might permanently remove all data. In case you do delete by mistake, there's a chance that you can get it back by contacting our awesome support people.

See our deleting a custom field tutorial to delete a custom field programmatically.

MethodURLUseful for
DELETE/dealFields/{id}Marking a deal field as deleted.
NB! Leads inherit all deals' custom fields.
DELETE/organizationFields/{id}Marking an organization field as deleted
DELETE/personFields/{id}Marking a person field as deleted
DELETE/productFields/{id}Marking a product field as deleted

After a custom field is deleted, it will no longer appear in API responses. All POST requests mentioning a custom field will ignore it.

Types of custom fields

See below the 16 different types of custom fields available:

Typefield_typeDescriptionUseful forAdditional info
Text varcharThe text field is used to store texts up to 255 charactersBilling addresses, (short) comments, email addresses
Autocomplete varchar_autoThe text field is used to store texts up to 255 characters and can autocomplete from the text previously inserted into this fieldCustom options (e.g., tagging), email addresses
Large texttextThe large text field is used to store texts longer than usualComments, descriptions
Numerical doubleThe numeric field is used to store data such as the amount of commission or other custom numerical dataCommission, priority levelThe value should be numeric with a maximum precision (decimal places) of 16.

If a number exceeds the maximum precision, it will stay without the full precision.
Monetary monetaryThe monetary field is used to store data such as the amount of commissionCommission, amountsThe currency of the field will match the user’s default currency setting unless specified otherwise in the request.

The format of the field is determined by the user’s locale.
Multiple options setThe multiple options field lets you predefine a list of values to choose from.

Multiple option fields can have a max of 10,000 options per field.
Industry type, competitors, region
Single option enumThe single option field lets you predefine a list of values out of which one can be selected.

Single option fields can have a max of 10,000 options per field.
Lead type, category, industry
User userThe user field can contain one user amongst users of your Pipedrive account*Tech contacts, previous deal owners
Organization orgThe organization field can contain one organization out of all the organizations stored on your Pipedrive account*Related parties, partner organizations
Person peopleThe person field can contain one person out of all the people stored on your Pipedrive account*Related parties, tech contacts
Phone phoneA phone number field can contain a phone number (naturally) or a Skype Name with a click-to-call functionalitySkype names, phone numbersNo auto-formatting unless enabled from the User Interface (supports only the US phone format)
Time timeThe time field is used to store times, picked from a handy inline time pickerDelivery times, lunchtime
Time range timerangeThe time range field is used to store time ranges picked from a handy inline time pickerOffice hours, the best time to contact
Date dateDate field is used to store dates picked from a handy inline calendarDelivery dates, deadlinesThe format of the field is determined by the user’s locale
Date range daterangeThe date range field is used to store date ranges picked from a handy inline calendarEvent dates, completion estimates
Address addressAddress field is used to store addressesEvent places, office locations (when separate from business address)The address field can hold all parts of address components – including City, tate, Zip Code, and Country – so there’s no need to create separate address fields for each address component.

You can use Google Maps autocomplete textfield to enter addresses and visualize them on a map. You’ll also be able to filter items based on specific address criteria.

* Doesn’t link the item with the user, person, or organization for statistics or any other form of ownership or relation, but can be used for filtering.

How to find out if a field is a custom field

The edit_flag parameter in the response body of an entity’s fields can be used to identify if the field is a custom field:

  • true – a custom field
  • false – Pipedrive default field
  id: 12499,
  key: '123456789',
  name: 'Date',
  order_nr: 47,
  field_type: 'date',
  json_column_flag: true,
  add_time: '2023-03-02 02:14:54',
  update_time: '2023-03-02 02:14:54',
  last_updated_by_user_id: 13053568,
  edit_flag: true,
  details_visible_flag: true,
  add_visible_flag: false,
  important_flag: true,
  bulk_edit_allowed: true,
  filtering_allowed: true,
  sortable_flag: true,
  mandatory_flag: false,
  active_flag: true,
  projects_detail_visible_flag: false,
  index_visible_flag: true,
  searchable_flag: false

Custom fields created by Contact Sync

When a user first sets up Contact Sync, five new custom fields (Instant messenger, Postal address, Notes, Birthday, Job title) are created for the entire company. These fields are similar to the default Pipedrive fields as they have a field API key that follows the syntax of all default Pipedrive API keys (field name, with an underscore replacing each space), unlike user-generated custom fields.

Here are the five custom fields created by Contact Sync:

Field nameTypeShow in Add new dialogShow in detail viewField API keyAdditional info
Instant messengerVarcharby default: Noby default: NoimAlthough this is a text field, it accepts an array of objects. (See example below)
Postal addressAddressby default: Noby default: Nopostal_address
NotesLarge Textby default: Noby default: Nonotes
BirthdayDateby default: Noby default: Nobirthday
Job titleTextby default: Noby default: Nojob_title

You can also see these fields in the Pipedrive web app by going to Settings > (Company) > Data fields > Person. It’s not possible to add any other fields to Contact Sync.

Contact Sync and custom fields duplication

Contact Sync directly affects these five fields, as the data for these fields is updated every time the Contact Sync source is updated. As such, when using these fields, please note that they may be duplicated by users who create custom fields with the same name. This can cause issues where the field names match, but the API keys do not because one has a Pipedrive API key and the other has a 40-character hashed API key. Therefore, a user may have two fields with different information in them.

Instant messenger field and labels

The instant messenger field (field key im) is a text field that accepts an array of objects. Do note that multiple labels are available for the different instant messengers, for example, Google, AIM, Yahoo, Skype, etc.

Here is an example of what an array for this field could look like:

    "label": "google",
    "value": "[email protected]",
    "primary": true
    "label": "aim",
    "value": "[email protected]",
    "primary": false