Working with labels

Within the Pipedrive web app, you can add visual labels to Deals, Persons, Organizations, and Leads. See the visual of how labels are displayed inside Pipedrive.

This guide will give you an overview of how to do the following things:

• How to find the values for each label?
• How to update and add labels?
• How to assign labels to an entity?

📘

The Deal, Person and Organization labels are custom fields. Keep in mind that a custom field with the type of "Single option" and "Multiple options" can have a maximum of 10,000 options per custom field.

---

Finding label values

---

The best way to find a label’s values is to make a GET request.

For Deals, Organizations, and Persons, you can make a GET request to the label’s corresponding custom field endpoint (see the following table). To help you out with the request, see updating custom fields' values tutorial.

For Leads, you can make a GET request to the label’s designated endpoint - GET /leadLabels.

When you first start working with labels, you should know that Pipedrive creates default values for Person and Organization labels and three default labels for the Lead entity. You can see the set labels from here or fetch them using the endpoints from the following table.

Label type	Endpoint
Labels for Deals	GET /dealFields
Labels for Organizations	GET /organizationFields
Labels for Persons	GET /personFields
Labels for Leads	GET /leadLabels

After making a request to fetch Deal/Organization/Person labels, you should find the label field from the response's payload and then look for the field ID of the title, the name ( "name": "label"), and the available options for the label property. Each label option has a label ID, color (if defined), and text which is displayed under the label parameter for Deals/Organizations/Persons. Try to store these as you'll need them when you'd like to update any of the labels.

For Lead labels, as you are using a designated endpoint, you should receive a list of data that shows all available labels and their descriptive parameters, for example, name and color.

If the label has no values

If the label doesn't have any values by default (options or data parameter isn't displayed), you'll need to add them by making a request to the corresponding update (PUT for Deals/Organizations/Persons or PATCH for Leads) endpoint.

Default label values and labels

Pipedrive creates default values for Person and Organization labels and three default labels for the Lead entity.

📘

For Person and Organization labels, the default values are color and label.

• The values for color and label may change depending on your language settings.
• The label id is dynamic and not constant.

For Lead labels, the default values are name and color. The label id is also dynamic and not constant.

Default values of Person labels (values of color and label are set by default):

JSON

"options":[
   {
      "color":"green",
      "label":"Customer",
      "id":1 //id is dynamic
   },
   {
      "color":"red",
      "label":"Hot lead",
      "id":2
   },
   {
      "color":"yellow",
      "label":"Warm lead",
      "id":3
   },
   {
      "color":"blue",
      "label":"Cold lead",
      "id":4
   }
]

Default values for Organization labels (values of color and label are set by default):

JSON

"options":[
   {
      "color":"green",
      "label":"Customer",
      "id":5 //id is dynamic
   },
   {
      "color":"red",
      "label":"Hot lead",
      "id":6
   },
   {
      "color":"yellow",
      "label":"Warm lead",
      "id":7
   },
   {
      "color":"blue",
      "label":"Cold lead",
      "id":8
   }
]

Default labels for Leads (values of name and color are set by default):

JSON

[
   {
      "id": "5e5faf00-b6e0-11ea-b5f6-45d1bda97e35",
      "name": "Hot",
      "color": "red",
      "add_time": "2020-06-25T12:35:36.000Z",
      "update_time": "2020-06-25T12:35:36.000Z"
   },
   {
      "id": "5e5faf01-b6e0-11ea-b5f6-45d1bda97e35",
      "name": "Cold",
      "color": "blue",
      "add_time": "2020-06-25T12:35:36.000Z",
      "update_time": "2020-06-25T12:35:36.000Z"
   },
   {
      "id": "5e5faf02-b6e0-11ea-b5f6-45d1bda97e35",
      "name": "Warm",
      "color": "yellow",
      "add_time": "2020-06-25T12:35:36.000Z",
      "update_time": "2020-06-25T12:35:36.000Z"
   }
]

---

Updating and adding labels

---

Labels for the Deal, Organization, and Person in the Deal's details view

Label for a Lead displayed in the Lead's details view

If you wish to change the default labels or add labels to the Deal/Organization/Person entity, you'll need to make a PUT request to one of the corresponding endpoints.
For the Lead entity, you’ll need to use the PATCH request to change a label and the POST request to add a label.

Entity	Endpoint	Required parameters for updating a label
Deal	PUT /dealFields/{id}	id (integer) - label field ID
Organization	PUT /organizationFields/{id}	id (integer) - label field ID
Person	PUT /personFields/{id}	id (integer) - label field ID
Lead (Updating a label)	PATCH /leadLabels/{id}	id (string) - label field ID
Lead (Adding a label)	POST /leadLabels	name (string) color (string)

Updating and adding label values for Deals, Organizations, and Persons

To update or add new labels, you'll need to send all the options for different labels in an array of objects. For example, if you want to update the label with "id": 1, you'll need to include all other labels, their data and then change what you want to change.

In this example, we changed the first label option from the Person entity to be purple and have the text of the label be Interested party.

JSON

{
    "options": [
        {
            "color": "purple",
            "label": "Interested party",
            "id": 1
        },
        {
            "color": "red",
            "label": "Hot lead",
            "id": 2
        },
        {
            "color": "yellow",
            "label": "Warm lead",
            "id": 3
        },
        {
            "color": "blue",
            "label": "Cold lead",
            "id": 4
        }
    ]
}

To add only one new label, you'll still need to include all of the previously existing labels you wish to keep. In this example, we added a gray label with the text Drafted to the options of Person labels.

JSON

{
   "options":[
      {
         "color":"green",
         "label":"Customer",
         "id":1
      },
      {
         "color":"red",
         "label":"Hot lead",
         "id":2
      },
      {
         "color":"yellow",
         "label":"Warm lead",
         "id":3
      },
      {
         "color":"blue",
         "label":"Cold lead",
         "id":4
      },
      {
         "label":"Drafted",
         "color":"gray"
      }
   ]
}

Updating Lead labels

The difference between Lead labels and other entity labels is the passing of less information as you can update one label or one field in a label at a time. With Deal/Organization/Person labels, you have to send all the data surrounding all existing label options.

To update a Lead label, you’ll only need to send the ID of the specific label you want to update with the parameter of the field that needs changing. For example, if you want to update the label with "id": 5e5faf00-b6e0-11ea-b5f6-45d1bda97e35, you'll need to include this ID and the corresponding parameter (name and/or color) with the value that you want to change to.

In this example, we changed the text of the first label from the Lead entity to be VIP and kept the original label color red.

JSON

[{
      "id": "5e5faf00-b6e0-11ea-b5f6-45d1bda97e35",
      "name": "VIP",
      "color": "red",
	}
]

Adding Lead labels

To add a Lead label, you’ll need to make a request to the POST /leadLabels endpoint and include the name and color parameters in the request body. Do take note that only a subset of colors can be used: green, blue, red, yellow, purple, and gray.

Sample request body
We added a Lead label with the name Tentative in the color gray.

JSON

{
   "name":"Tentative",
   "color":"gray"
}

node.js

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 addLeadLabel() {
    try {
        console.log('Sending request...');

        const api = new pipedrive.LeadLabelsApi(defaultClient);

        const data = {
            name: 'Tentative',
            color: 'gray'
        }
        const response = await api.addLeadLabel(data);

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

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


addLeadLabel();

---

Assigning a label to an entity

There are two different ways of adding a label:

1. The ID of the label is already known, so you add them when you create an entity.
2. The label ID is not known, so you'll need to fetch the IDs first and then update the entity to have the label.

📘

For Deals, Organizations, and Persons, the behavior and logic are similar in all three cases, so we'll continue using Deals as a sample entity.

For Leads, the behavior and logic differ slightly, so we’ve explained it below.

Adding a label when creating the Deal/Organization/Person entity

Authentication
First, you need to think about how you authenticate your request to our API. You can either use an API token (see the code snippet below) or OAuth. For more information about authenticating your requests, see our authentication article. For more detailed guidance, check out the creating a Deal tutorial.

PHP

// Pipedrive sample API token
$api_token = '659c9fddb16335e48cc67114694b52074e812e03';
// Pipedrive sample company domain
$company_domain = 'efficient-company';

Sample Code
Use the following URL for an API token request when adding a Deal.

PHP

// URL for creating a deal
$url = 'https://' . $company_domain . '.pipedrive.com/api/v1/deals?api_token=' . $api_token;

Be sure to add the $api_token, $company_domain and $url parameters after the <?php tag in the following code sample.

PHP

<?php

// Title of the Deal and the ID of the label that you want it to be assigned
$data = array(
    'title' => 'Slack deal',
    'label' => 10
);

$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 the data returned in the result is not empty
if (empty($result['data'])) {
    exit('Adding failed' . PHP_EOL);
}

// Check if Deal ID came back, if it did, print out success message
if (!empty($result['data']['id'])) {
    echo 'Deal added successfully! ' . PHP_EOL;
}

Adding a label through updating the Deal/Organization/Person entity

First, fetch the label option's ID by making a GET request to GET /dealFields. This is similar to the finding the label values section.

Second, update a deal by making a PUT request to PUT /deals/{id}. There you'd need to add the label ID as a part of the data like this:

JSON

// The ID of the label you want the deal to have. ID's can be changed and fetched through corresponding custom field's endpoint e.g. dealFields
$data = array(
  'label' => 10
);

Check out this tutorial about updating a deal for more detailed help on this request.

Adding a label when creating the Lead entity

Authentication
Same with the Deal/Organization/Person entity, you need to think about how you authenticate your request to our API. You can either use an API token (see the code snippet below) or OAuth. For more information about authenticating your requests, see our authentication article. For more detailed guidance, check out Adding a Lead tutorial.

For authentication with api_token:
Use the following URL for an API token request when adding a Lead. Replace COMPANYDOMAIN and APITOKEN with your own values.

URL

https://{COMPANYDOMAIN}.pipedrive.com/v1/leads?api_token=APITOKEN

For authentication with OAuth 2.0 (URL):
Use the following URL for an OAuth request when adding a Lead. Replace COMPANYDOMAIN with your own values.

URL

https://{COMPANYDOMAIN}.pipedrive.com/api/v1/leads

Request body
The title is the only required field here. The person_id can also be replaced by the organization_id.

JSON

{
  "title": "Superman lead",
  "person_id": 33,
  "label_ids": [
                "5e5faf00-b6e0-11ea-b5f6-45d1bda97e35",
                "5e5faf01-b6e0-11ea-b5f6-45d1bda97e35"
  ]
}

node.js

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 addLabel(name, color) {
    console.log('Adding label...')

    const api = new pipedrive.LeadLabelsApi(defaultClient);

    const label = await api.addLeadLabel({
        name,
        color
    })
    return label.data.id
}

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

        const api = new pipedrive.LeadsApi()
        const redLabel = await addLabel('Custom Label 1', 'red');
        const greenlabel = await addLabel('Custom Label 2', 'green');
        const data = {
            title: 'Superman lead',
            person_id: 1,
            label_ids: [ // label_ids takes an array of label ids that you can create with addLeadLabelApi
                redLabel,
                greenlabel
            ]
        }
        const response = await api.addLead(data);

        console.log('Added lead with labels', response)
    } catch (err) {
        const errorToLog = err.context?.body || err;

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

addLead();

Adding a label when updating the Lead entity

First, fetch the Lead’s ID by making a GET request to GET /leads endpoint and the label ID(s) by making a GET request to GET /leadLabels endpoint.  This is similar to the finding the label values section.

Second, update a lead by making a PATCH request to PATCH/leads/{id}. There, you’d need to add both the Lead ID and label’s ID(s).

For authentication with api_token:
Use the following URL for an API token request when updating a Lead. Replace COMPANYDOMAIN, APITOKEN, and LEADID with your own values.

URL

https://{COMPANYDOMAIN}.pipedrive.com/v1/leads/{LEADID}?api_token=APITOKEN

For authentication with OAuth 2.0 (URL):
Use the following URL for an OAuth request when updating a Lead. Replace COMPANYDOMAIN and LEADID with your own values.

URL

https://{COMPANYDOMAIN}.pipedrive.com/api/v1/leads/{LEADID}

Request body

JSON

{
  "id": "151769a0-8e17-11eb-b241-67680ba8ab9e",
  "label_ids": [
                "503293e1-8636-11eb-b535-7bc3308b2163",
                "837050a0-8d78-11eb-802a-333d26037251"
  ]
}

node.js

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 addLabelToLead() {
    try {
        console.log('Sending request...');

        const api = new pipedrive.LeadsApi(defaultClient);

        const LEAD_ID = 'ab5ded60-4188-11ec-a3a5-2f49d1d4a1c9';
        const data = {
            label_ids: ['9e1fbed0-5420-11ec-8528-e958c9fad8e7']
        }
        const response = await api.updateLead(LEAD_ID, data);

        console.log('Label has been successfully added to lead!', response);
    } catch (err) {
        const errorToLog = err.context?.body || err;

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

addLabelToLead()