Pipedrive API Documentation

Pipedrive's API Docs

Welcome to Pipedrive's Developer Documentation. Here you'll find comprehensive guides and documentation to help you start working with Pipedrive's API, as well as the Changelog to see any relevant changes regarding the public API.

Custom fields

Custom fields give you the opportunity 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 their own uses.

Creating a custom field

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

Method
URL
Useful for

POST

Adding a new Deal field.
NB! Leads inherit all Deal's custom fields.

POST

Adding a new Organisation field

POST

Adding a new Person field

POST

Adding 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 which they are referenced by in our API.

Naming a custom field

All custom fields are referenced to 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 is 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/v1/deals?api_token=' . $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);
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.

Method
URL
Useful for

PUT

Updating a Deal field.
NB! Leads inherit all Deal's custom fields.

PUT

Updating an Organisation field.

PUT

Updating a Person field.

PUT

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.

Method
URL
Useful for

DELETE

Marking a Deal field as deleted.
NB! Leads inherit all Deal's custom fields.

DELETE

Marking an Organisation field as deleted.

DELETE

Marking a Person field as deleted.

DELETE

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:

Type
field_type
Description
Useful for
Additional info

Text

varchar

Text field is used to store texts up to 255 characters

Billing addresses, (short) comments, email addresses

Autocomplete

varchar_auto

Text field is used to store texts up to 255 characters and can autocomplete from the text previously inserted into this field

Custom options (for example tagging), email addresses

Large text

text

Large text field is used to store texts longer than usual

Comments, descriptions

Numerical

double

Numeric field is used to store data such as amount of commission or other custom numerical data

Commission, priority level

Value should be numeric

Monetary

monetary

Monetary field is used to store data such as amount of commission

Commission, amounts

Currency of the field will match User's default currency setting, unless specified otherwise in the request.

Format of the field is determined by the User's locale.

Multiple options

set

Multiple options field lets you predefine a list of values to choose from

Industry type, competitors, region

Single option

enum

Single option field lets you predefine a list of values out of which one can be selected

Lead type, category, industry

User

user

User field can contain one user amongst users of your Pipedrive account*

Tech contacts, previous deal owners

Organization

org

Organization field can contain one organization out of all the organizations stored on your Pipedrive account*

Related parties, partner organizations

Person

people

Person field can contain one person out of all the people stored on your Pipedrive account*

Related parties, tech contacts

Phone

phone

A phone number field can contain a phone number (naturally) or a Skype Name with a click-to-call functionality

Skype names, phone numbers

No auto-formatting unless enabled from the User Interface (supports only the US phone format)

Time

time

Time field is used to store times, picked from a handy inline timepicker

Delivery times, lunch time

Time range

timerange

Time range field is used to store time ranges, picked from a handy inline timepicker

Office hours, best time to contact

Date

date

Date field is used to store dates, picked from a handy inline calendar

Delivery dates, deadlines

Format of the field is determined by the User's locale.

Date range

daterange

Date range field is used to store date ranges, picked from a handy inline calendar

Event dates, completion estimates

Address

address

Address field is used to store addresses

Event places, office locations (when separate from business address)

Address field can hold all parts of address components - including City, State, Zip Code, Country - so there's no need to create separate address fields for each address component. You'll be able to use Google Maps autocomplete textfield for entering 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.

Custom fields created by Contact Sync

When a user first sets up Contact Sync, 5 new custom fields (Instant messenger, Postal address, Notes, Birthday, Job title) are created to 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.

See below the 5 custom fields created by Contact Sync:

Field name
Type
Show in Add new dialog
Show in details view
Field API key

Instant messenger

Text

by default: No

by default: No

im

Postal address

Address

by default: No

by default: No

postal_address

Notes

Large Text

by default: No

by default: No

notes

Birthday

Date

by default: No

by default: No

birthday

Job title

Text

by default: No

by default: No

job_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.

These fields are directly affected by Contact Sync as the data is updated every time it's updated from the source of the Contact Sync. 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.

Updated 4 months ago


Custom fields


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.