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 an app panel

Terminology


App panels - An entrance point for an app's data and interactivity inside Pipedrive in a panel format.

Object - App panel object is a data entry point with multiple descriptive fields displayed inside a panel. A panel can contain multiple objects.

Field - Descriptive data field in a certain format within the object.

Global actions - A green action button at the bottom of the app panel. It features one primary app action and a dropdown menu if there are multiple app actions and/or an external link.


How can I add an app panel in Marketplace Manager?


You can add the app panels to the Pipedrive UI either when registering the app or updating the existing app. For that, you need to fill in the following fields in Marketplace Manager in Pipedrive's UI:

Field
Description

Panel name (required)

Descriptive, max 30 characters

API endpoint (required)

The URL of the endpoint which we'll use to fetch the data of the object properties

HTTP Auth username and password (required)

Our service will send the HTTP request with these credentials as the Basic Authentication header to protect your data. To protect your data, we strongly recommend using authenticated HTTPS requests. Note that we do not support self-signed certificates.

JSON data structure (required)

A JSON file that describes the structure of your app panel seen in the Pipedrive UI

Panel location

Choose where the panel would be displayed:

  • Deals details view
  • People details view
  • Organizations details view

Panel actions

Panel actions can be added in the same section of Marketplace Manager where you add your panels: App extensions > App panels. Once you’ve added your panel and saved your app, a new “+ Actions to this panel” link will appear. Find out how to add actions in panels here.

JSON data structure

To create the app panel displayed in Pipedrive's UI, you need to add it as a JSON file to Marketplace Manager with a JSON schema defining the app panel's structure.

The app panel can have a maximum of 10 objects which are titled by headers and contain a maximum of 20 fields (excluding the header field), all of which should be defined in the JSON schema. You can also use the single object app panel template or multiple object app panel template for defining your JSON schema.

Fields

In the JSON Schema, you can specify the fields that your app panel will contain. These fields should be added to JSON Schema as properties. We support the following types of field definitions:

Keep in mind that if the data received from your API endpoint does not match the required data types, the whole app panel's data will not be displayed and the user will see an error message stating "Something went wrong…".

Object property
Object property type
Format requirements for the response
Examples and explanations

Text

$ref: "#/definitions/text"

"markdown": true needs to be added adding links with labels. More in Text in API response.

Can contain links, emails, bold text, numbered lists and bulleted lists.
Links can be displayed with labels by using markdown. See Text in API response.
Truncated after 255 characters

Numerical

$ref: "#/definitions/numerical"

12.00
12,00

Date

$ref: "#/definitions/date"

YYYY-MM-DD

2018-11-23

Time

$ref: "#/definitions/time"

hh:mm:ssZ

20:20:39+02:00

DateTime

$ref: "#/definitions/date-time"

YYYY-MM-DDThh:mm:ssZ

2018-11-13T20:20:39+02:00

Email

$ref: "#/definitions/email"

Link

$ref: "#/definitions/link"

Phone number

$ref: "#/definitions/phone"

+3725000001

Address

$ref: "#/definitions/address"

460 Park Ave South, New York, NY 10016, USA

Currency

$ref: "#/definitions/currency"

USD 200,99

Label

$ref: "#/definitions/label"

See how label should be defined in your API response.
Available colors for the label:

  • Green (#08A742)
  • Red (#F94839)
  • Blue (#317AE2)
  • Yellow (#FFCC00)
  • Purple (#721EA9)
  • Grey (#B9BABB)

Label's text is truncated after 40 characters
Label's text should be in sentence case e.g Potential client

Tags

$ref:"#/definitions/tags"

An array of strings representing tag labels need to be sent back in the API response. See more in Tags in API response.

One, Two, Three

In our JSON Schema the additionalProperties keyword is set to false by default, so you can only send values to those properties that are defined. If you send data that isn't defined properly under properties, the panel won't be rendered correctly and the user will see an error. For more information regarding how we'll display the property's data see understanding JSON Schema and additional properties.

The ordering of fields

The set of properties will be rendered to the list of fields in the app panel according to the way they are defined in the JSON Schema. The only exception is the header field, which will be excluded from the array and moved to the header of the app panel's object. For example, if in properties the fields are defined in order of id, header, name and email, then the order visible in the UI's app panel would start out with the app panel's object header and have name and email as fields.

Text in API response

Visual of text object property

Visual of textobject property

Response example of text with markdown support. Value object only supports adding labels to links in markdown in the format shown in the sample below:

{
  "note": {
    "markdown": true,
    "value": "Meeting next week to sign the [insurance contract](pipedrive.com).\n\n \n\n **Agenda**\n1. Agree on contract details\n\n **Links**\n - [Insurance company](https://www.pipedrive.com/en/features)"
  }
}

Currency in API response

Visual of currency object property

Visual of currencyobject property

currency object property should be defined as an object in the API response and values for code and value properties should be given. code is the ISO-4217 format currency code for non-custom currencies (custom currencies cannot be added or removed via the API, only admin users of the account can configure them from the Pipedrive web app). Overall, code is matched to the codes defined in Pipedrive and if the currency is already defined with a symbol, the symbol is shown instead of the currency code in the app panel.

"delivery_cost": {
    "code": "USD",
    "value": 2000.00
}

Label in API response

Visual of label object property

Visual of labelobject property

label object property should be defined as an object in the API response and values for color and label properties should be given. label's colors can be green, red, blue, yellow, purple, grey. Label's text of the label object property can be 40 characters long before truncated.

"label": {
    "color": "yellow",
    "label": "Assembling"
}

Tags in API response

Visual of tags

Visual of tags

Tag labels need to be sent in an array of strings format, where each string will represent one tag.
Tags will be displayed in the app panel as separate unclickable labels.

"tags": ["Cruise control", "Rain detector", "Lane assist"]

Header field

For single object panels, the header is a separate optional field that defines the header of the app panel, e.g. "GTA 22 Blue Auto".
For multiple object panels, the header field is required as it’s the title of each object within the panel, e.g. "GTA 22 Blue Auto", “BNW X500”, “Dorche 911”. You can define the header field the same way you have defined all other fields:

{
    "type": "array",
    "items": {
        "type": "object",
        "required": [
            "id"
        ],
        "properties": {
            "id": {
                "$ref": "#/definitions/numerical"
            },
            "header": {
                "$ref": "#/definitions/header"
            }
        }
    }
}

External links

You can add two types of external links to an app panel - a link to app settings and an external link at the bottom of the global actions dropdown menu. As both of these links are added by extending the API response, the URLs and labels can be changed dynamically.

App settings

An external link to app settings is displayed under the actions menu on the top right-hand corner of the app panel.

External link - app settings

External link - app settings

To add a link for app settings, you'd need to extend the API response by adding a settings object next to the data as seen in the example code below. The settings object should contain the URL property of the link.

{
    "data": [ ... ],
    "settings": {
        "url": "https://google.com"
    }
}

External link - global actions

The external link at the bottom of the global actions dropdown menu can be used to have an entrance link to your app right inside the app panel. You can add one external_link per app panel.

External link - global actions

External link - global actions

To add an external link for your app to the app panel's footer, you will need to extend the API response by adding an external_link object next to the data as seen in the example code below. The label property should be descriptive text in sentence case that explains to the user what happens when the link is clicked. The label property will be fully visible in the length of 40 characters, after that it'll be truncated.

{
    "data": [ ... ],
    "external_link": {
        "url": "https://google.com",
        "label": "Update billing"
    }
}

If your app panel has an app action(s) defined for global actions, the external link will appear at the bottom of the global actions dropdown menu, as the last action.

External link - blue text link

External link - blue text link

If your app panel has no app actions defined for global actions, the external link will appear as a blue text link at the bottom of your app panel.

Actions in panels

Once you have added a JSON file to Marketplace Manager with a JSON schema defining the app panel's structure, you can then add various actions within the panel.

App actions can be added for the entire panel/app, the object itself and individual fields.


Panel error handling


Interactive app panel error state

Interactive app panel error state

Your app panel can encounter different error scenarios when a user is using it. To show an interactive error state when an error happens, your app has to return a non-success status code (>300) with the following data:

Field
Description

title (required)

Descriptive, max 30 characters

subtitle (optional)

A markdown field where you can add a longer message with links.

action (optional)

A call-to-action with URL and label fields

{
    "error": {
        "title": "Subscription expired",
        "subtitle": "Please [view your billing settings](https://pipedrive.com) or contact our customer support.",
        "action": {
            "url": "https://pipedrive.com",
            "label": "Renew subscription"
        }
    }
}


Templates


Example of multiple object panel

To have an app panel containing multiple objects, you can refer the objects in the form of an array, where the fields of the app panel are defined in properties. All labels of fields should be in sentence case. For easy access to the sample panel, use this template for defining your JSON schema for multiple object app panel.

{
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "id",
      "header"
    ],
    "properties": {
      "id": {
        "$ref": "#/definitions/numerical"
      },
      "header": {
        "$ref": "#/definitions/header"
      },
      "project": {
        "$ref": "#/definitions/text"
      },
      "manufacturer": {
        "$ref": "#/definitions/text"
      },
      "delivery_date": {
        "$ref": "#/definitions/date-time",
        "label": "Delivery date"
      },
      "status": {
        "$ref": "#/definitions/label"
      },
      "delivery_company": {
        "$ref": "#/definitions/text",
        "label": "Delivery company"
      },
      "tracking": {
        "$ref": "#/definitions/text"
      },
      "note": {
        "$ref": "#/definitions/text"
      },
      "extras": {
        "$ref": "#/definitions/tags"
      },
      "delivery_cost": {
        "$ref": "#/definitions/currency",
        "label": "Delivery cost"
      }
    }
  }
}

The URL you add to the Marketplace Manager should respond with the data, which is received from the API and is structured as in the following example. If there's no data or the value null sent back in the response for one property, this property's data will be displayed as empty.

Multiple object app panel example

Multiple object app panel example

{
    "data": [
        {
            "id": 1,
            "header": "GTA 22 Blue Auto",
            "project": "New cars",
            "manufacturer": "Molksvagen LLC",
            "delivery_date": "2021-08-31T07:00:00.000Z",
            "status": {
                "color": "yellow",
                "label": "ASSEMBLING"
            },
            "delivery_company": "Jungle Prime",
            "tracking": {
                "markdown": true,
                "value": "[Open tracking link](https://pipedrive.com)"
            },
            "note": {
                "markdown": true,
                "value": "Meeting next week to sign the [insurance contract](https://pipedrive.com)."
            },
            "extras": [
                "Cruise control",
                "Rain detector",
                "Lane assist"
            ],
            "delivery_cost": {
                "code": "USD",
                "value": 2000
            }
        },
        {
            "id": 2,
            "header": "BNW X500",
            "project": "New cars",
            "manufacturer": "Molksvagen LLC",
            "delivery_date": "2021-08-31T07:00:00.000Z",
            "status": {
                "color": "red",
                "label": "DELAYED"
            },
            "delivery_company": "Jungle Prime",
            "tracking": {
                "markdown": true,
                "value": "[Open tracking link](https://pipedrive.com)"
            },
            "note": {
                "markdown": true,
                "value": "Meeting next week to sign the [insurance contract](https://pipedrive.com)."
            },
            "extras": [
                "Cruise control",
                "Rain detector",
                "Lane assist"
            ],
            "delivery_cost": {
                "code": "USD",
                "value": 2000
            }
        },
        {
            "id": 3,
            "header": "Dorsche 911",
            "project": "New cars",
            "manufacturer": "Molksvagen LLC",
            "delivery_date": "2021-08-31T07:00:00.000Z",
            "status": {
                "color": "green",
                "label": "EN ROUTE"
            },
            "delivery_company": "Jungle Prime",
            "tracking": {
                "markdown": true,
                "value": "[Open tracking link](https://pipedrive.com)"
            },
            "note": {
                "markdown": true,
                "value": "Meeting next week to sign the [insurance contract](https://pipedrive.com)."
            },
            "extras": [
                "Cruise control",
                "Rain detector",
                "Lane assist"
            ],
            "delivery_cost": {
                "code": "USD",
                "value": 2000
            }
        }
    ],
    "external_link": {
        "url": "https://pipedrive.com",
        "label": "Account settings"
    },
    "settings": {
        "url": "https://pipedrive.com"
    }
}

The response should be empty when the app panel doesn’t have an entity tied to it on the app’s side. For example, when there’s no connection between a deal and a project on the app’s end, we'll only display an error message stating "Nothing to show" under the app panel’s name.

{
  data: [
    ]
}
Empty state error message

Empty state error message

Example of single object app panel

The app panel can also consist of only one object (see the code below). You can click here for the sample template for defining your JSON schema for a single object app panel.

{
    "type": "object",
    "required": [
        "id",
        "header"
    ],
    "properties": {
        "id": {
            "$ref": "#/definitions/numerical"
        },
        "header": {
            "$ref": "#/definitions/header"
        },
        "project": {
            "$ref": "#/definitions/text"
        },
        "manufacturer": {
            "$ref": "#/definitions/text"
        },
        "delivery_date": {
            "$ref": "#/definitions/date-time",
            "label": "Delivery date"
        },
        "status": {
            "$ref": "#/definitions/label"
        },
        "delivery_company": {
            "$ref": "#/definitions/text",
            "label": "Delivery company"
        },
        "tracking": {
            "$ref": "#/definitions/text"
        },
        "note": {
            "$ref": "#/definitions/text"
        },
        "extras": {
            "$ref": "#/definitions/tags"
        },
        "delivery_cost": {
            "$ref": "#/definitions/currency",
            "label": "Delivery cost"
        }
    }
}

Example response:

{
    "data": {
        "id": 1,
        "header": "GTA 22 Blue Auto",
        "project": "New cars",
        "manufacturer": "Molksvagen LLC",
        "delivery_date": "2021-08-31T07:00:00.000Z",
        "status": {
            "color": "yellow",
            "label": "ASSEMBLING"
        },
        "delivery_company": "Jungle Prime",
        "tracking": {
            "markdown": true,
            "value": "[Open tracking link](https://pipedrive.com)"
        },
        "note": {
            "markdown": true,
            "value": "Meeting next week to sign the [insurance contract](https://pipedrive.com)."
        },
        "extras": [
            "Cruise control",
            "Rain detector",
            "Lane assist"
        ],
        "delivery_cost": {
            "code": "USD",
            "value": 2000
        }
    }
}

Also, note that the response should be empty when the app panel doesn’t have an entity tied to it on the app’s side. For example, when there’s no connection between a deal and a project on the app’s end, we'll only display an error message stating "Nothing to show" under the app panel’s name.

{
  data: {
  }
}

Updated 22 days ago


Adding an app panel


Suggested Edits are limited on API Reference Pages

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