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.

Adding a new custom field

Custom fields give you the opportunity to add out of the box 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, you can check them out here.

Follow the next steps to add a new custom field.

In this example, we're going to add a new custom Deal field, but you can apply this tutorial to any of the abovementioned items.

If you only want to see the finished code of this example, you can find it below.

Step 1: Get your API token and company domain

Follow our tutorials on how to find the API token and how to get the company domain. Then create a file addNewCustomDealField.php and first give value to the $api_token and $company_domain variables:

<?php
// Content of addNewCustomDealField.php
   
// Pipedrive API token
$api_token = 'Your API token goes here';
   
// Pipedrive company domain
$company_domain = 'Your company domain goes here';

Step 2: Prepare the data

In order to create a new custom field, there are two required parameters you have to give value to:

  • you need to decide on what you're going to name the new custom field (read more about naming custom fields)
  • what field_type it's going to be (see the field types once more if needed)
// Custom field name and type of field
$data = array(
  'name' => 'insert the name of the custom field here',
  'field_type' => 'insert the type of the field here'
);

Step 3: Define target URL

Based on to what item you've decided to add a custom field, you have to replace the endpoint in the request URL for the correct one:

Method
URL
Useful for

POST

Adding a custom Deal field

POST

Adding a custom Organisation field

POST

Adding a custom Person field

POST

Adding a custom Product field

Since in this example we're adding a new custom field to a Deal using PHP with our API, we then need to use POST /dealFields endpoint from the table above.

An example URL for adding a custom Deal field would look like this https://companydomain.pipedrive.com/api/v1/dealFields?api_token=659c9fddb16335e48cc67114694b52074e812e03

You need to create a $url variable which holds the correct URL for adding a new custom field for your chosen item. Here's a URL for adding a new custom Deal field:

// URL for adding a new custom field
$url = 'https://' . $company_domain . '.pipedrive.com/api/v1/dealFields?api_token=' . $api_token;

Step 4: Make a POST request

This part of the code is more complex and you don’t need to understand it right away, all you need to know is that it contains everything to make a POST request with your data against our API. Simply copy and paste this:

$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, $data);
  
echo 'Sending request...' . PHP_EOL;
  
$output = curl_exec($ch);
curl_close($ch);

Step 5: Check the result

$output variable holds the full response you get back from the server. As all responses from us are in JSON format, the first thing you'll want to do is to convert it into a proper PHP array:

// Create an array from the data that is sent back from the API
// As the original content from server is in JSON format, you need to convert it to PHP array
$result = json_decode($output, true);

Then you can check if data returned in the result is not empty:

// Check if the data returned in the result is not empty
if (empty($result['data'])) {
    exit('Adding failed' . PHP_EOL);
}

After that, you should check if a newly created custom Deal field id came back. If it did, then this means a new custom Deal field was added successfully:

// Check if a newly created custom field ID came back, if did, print out the ID and the name
if (!empty($result['data']['id'])) {
    echo 'Custom field was added successfully!'
      . $result['data']['title'] . ' (Custom field API key: ' . $result['data']['key'] . ')' . PHP_EOL;
  }

Full working example

Copy the full working example into addNewCustomDealField.php. Don't forget to replace variables with your actual data:

<?php
// Content of addNewCustomDealField.php
   
// Pipedrive API token
$api_token = '659c9fddb16335e48cc67114694b52074e812e03';
   
// Pipedrive company domain
$company_domain = 'theunicorntail';
 
// Custom field name and type of field
$data = array(
    'name' => 'Random name for a custom field',
    'field_type' => 'double'
  );
 
  // URL for adding a new custom field
  $url = 'https://' . $company_domain . '.pipedrive.com/api/v1/dealFields/?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, $data);
  
echo 'Sending request...' . PHP_EOL;
  
$output = curl_exec($ch);
curl_close($ch);
 
// Create an array from the data that is sent back from the API
// As the original content from server is in JSON format, you need to convert it to PHP array
$result = json_decode($output, true);
 
// Check if a newly created custom field ID came back, if did, print out the ID and the name
if (!empty($result['data']['id'])) {
    echo 'Custom field was added successfully!'
      . $result['data']['title'] . ' (Custom field API key: ' . $result['data']['key'] . ')' . PHP_EOL;
  }

Execute the code

Use php addNewCustomDealField.php command to execute the code in the command line.
Here's an example output if the custom Deal field was added:

$ php addNewCustomDealField.php
Sending request...
Custom field was added successfully! (Custom field API key: {key})

If adding the custom Deal failed, this is the output you'll get:

Sending request...
Adding failed

Updated 4 months ago


Adding a new custom field


Suggested Edits are limited on API Reference Pages

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