Custom fields

Custom fields allow you to add additional data to your Pipedrive account that isn't included by default. Each deal, organization, person, product, and project 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.

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.

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 Company settings > Data fields and choosing the entity (Deal/Person/Organization/Product/Project). Click the three-dot menu on the right-hand side of a custom field row and choose Copy API key.

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):

<?php
$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 = 'https://companydomain.pipedrive.com/api/v2/deals';
$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, json_encode($deal));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-token: ' . $api_token,
    'Content-Type: application/json'
]);

$output = curl_exec($ch);
curl_close($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.

Deleting a custom field

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

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:

*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:

You can also see these fields in the Pipedrive web app by going to Company settings > 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
  }
]