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 above-mentioned items.

If you only want to see the finished code of this example, you can find it below in PHP and in node.js .

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 what item you've decided to add a custom field to, you have to replace the endpoint in the request URL for the correct one:

Method	URL	Useful for
`POST`	`/dealFields`	Adding a custom Deal field
`POST`	`/organizationFields`	Adding a custom Organisation field
`POST`	`/personFields`	Adding a custom Person field
`POST`	`/productFields`	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 that 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;
  }

//All tutorial Node.Js code examples are for reference only and shouldn’t be used in production code as is. In production, a new new pipedrive.ApiClient() instance should be initialised separately for each request.
const pipedrive = require('pipedrive');
const defaultClient = new pipedrive.ApiClient();

// Configure authorization by settings api key
// PIPEDRIVE_API_KEY is an environment variable that holds real api key
defaultClient.authentications.api_key.apiKey = process.env.PIPEDRIVE_API_KEY;

async function addNewCustomDealField() {
    try {
        console.log('Sending request...');

        const api = new pipedrive.DealFieldsApi(defaultClient);

        const response = await api.addDealField({
            name: 'Random name for a custom field',
            field_type: 'double',
        });

        console.log('Custom field was added successfully!', response);
    } catch (err) {
        const errorToLog = err.context?.body || err;

        console.log('Adding failed', errorToLog);
    }
}

addNewCustomDealField();

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