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.

Embedded app actions


What are Embedded app actions?


Embedded app actions allow apps to provide a way for users to do as much as possible without leaving Pipedrive, e.g. the app can use Embedded actions to add contacts to email campaigns, change the status of a document, push the latest deal changes to linked documents, and create tasks in project management tools - all from a modal view that can be customized based on your app’s needs.

Embedded actions can be initiated from the action menu and the app panel settings menus. After an Embedded action has been clicked, a new modal containing Blocks and Action buttons will appear, where users can complete the action.

The visibility and availability of Embedded actions will stay the same as for Basic app actions, meaning that an app can have 24 app actions altogether, either Basic or Embedded, divided between different views (see detailed visibility in the UI). Embedded actions don’t work for shared apps - users need to install apps themselves to use embedded actions.

Embedded action is triggered from the app panel

Embedded action is triggered from the app panel

Embedded action can be also triggered from the three-dot actions menu

Embedded action can be also triggered from the three-dot actions menu

The modal of the embedded action is displayed after the action is clicked

The modal of the Embedded action is displayed after the action is clicked


The structure of the Embedded app action's modal


The Embedded app action will display a container called modal after it has been triggered. Each modal can contain up to 8 different types of UI elements called Blocks.

Key terminology:

Container - is a base UI element that will include different smaller customizable elements to show information from apps.

Modal - is currently the only container offered. Modal’s base layout is non-configurable. Each embedded action can display one modal, and each modal can contain up to 10 Blocks.

Components - are all UI elements that can be added to the Embedded app action’s modal, e.g. Blocks and Action buttons.

Blocks - smaller UI elements that can be included inside a modal, e.g., texts, multi-select, etc. The full list of available Blocks is available here.

Modal form - a combination of information and Blocks displayed inside the modal.

Action buttons - buttons in the footer of a modal that trigger the modal's action, this can be submitting, resetting, and cancelation.

The structure of the modal for Embedded action

The structure of the modal for Embedded action


How to create an Embedded action?


Key steps

  1. Plan out your use case.

  2. Map your use case with the most suitable Blocks for your modal - see Component library for a full list of available Blocks and how to add them to the schema.

  3. Create the schema. Validation of the schema can be done in Marketplace Manager.

    1. 1 Configure an API endpoint on your side to respond to Pipedrive’s request. The endpoint should be able to respond/return different sets of data based on the user's input choices.
  4. Configure the JWT token. The JWT token is used to secure the requests done from the Embedded action. We send the security token on each request. The JWT token can be decrypted with one value on the app's side. You can also specify a JWT secret value to the requests by adding it under JWT secret in Marketplace Manager when combining your Embedded action. If no JWT secret is added in the Marketplace Manager, we send the client secret as this value by default.

  5. Add your Embedded action’s schema to Marketplace Manager. If you already have a live app, please create another test app for testing out the embedded actions.

Adding the action in Marketplace Manager

Go to your app’s edit page in Marketplace Manager and scroll to the App extensions' section.

Click on “Add new action” under App actions and select “Embedded action” as the Action type, the form will slightly change depending on which type of App action you'll choose.
Next, fill in the name of the Embedded action and the rest of the fields.

Field
Description

Action name

The name of the Embedded app action. The name should be short (max 30 characters), actionable, and sentenced cased (only capitalize the first word).

Action type

Embedded action

API endpoint URL

All API requests related to this action will be sent to this URL.

Action location

Maximum 3 actions per location. There can be 24 different app actions in total, either Basic or Embedded, per app. See more about available locations in app action’s visibility.

JWT Secret

If left empty, client_secret will be used by default.

JSON data structure

The JSON schema for your Embedded action.


Schema


Embedded action's schema

The following example schema is the complete schema for the sample modal shown in the modal structure section above.

The JSON schema consists of a mapping of all blocks and actions that will be displayed in the Embedded app action’s modal for the user. More on which components to add and what options they offer, see Component library, for seeing how to display success and error messages inside the modal, see the User interaction handling page.

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_cake_size":{
                    "$ref":"#/definitions/element-input",
                    "options":{
                        "label":"Cake size",
                        "placeholder":"Insert size",
                        "message":"Cake size will be either S, M or L"
                    }
                },
                "block_key_textarea":{
                    "$ref":"#/definitions/element-textarea",
                    "options":{
                        "label":"Additional instructions",
                        "placeholder":"Write \"Happy Birthday!\" on the cake!",
                        "message":"What would you like to have on your cake?",
                        "resize":true
                    }
                },
                "block_key_separator":{
                    "$ref":"#/definitions/element-separator"
                },
                "block_key_flavors":{
                    "$ref":"#/definitions/element-checkbox-group",
                    "options":{
                        "label":"Flavor",
                        "value":[
                            "cranberry"
                        ],
                        "items":[
                            {
                                "value":"vanilla",
                                "label":"Vanilla"
                            },
                            {
                                "value":"chocolate",
                                "label":"Chocolate",
                                "isDisabled":true
                            },
                            {
                                "value":"cranberry",
                                "label":"Cranberry"
                            }
                        ]
                    }
                },
                "block_key_delivery_date":{
                    "$ref":"#/definitions/element-datepicker",
                    "options":{
                        "label":"Delivery date",
                        "value":"2020-02-27",
                        "message":"Cakes will be ready by 12:00 on selected date",
                        "placeholder":"Date",
                        "allowClear":true,
                        "isRequired":true
                    }
                },
                "block_key_delivery_method":{
                    "$ref":"#/definitions/element-select",
                    "options":{
                        "label":"Delivery method",
                        "placeholder":"Select method",
                        "message":"Please, specify how the delivery will be done",
                        "isRequired":true,
                        "items":[
                            {
                                "label":"Standard",
                                "value":1
                            },
                            {
                                "label":"Accelerated",
                                "value":2
                            }
                        ]
                    }
                },
                "block_key_is_gift":{
                    "$ref":"#/definitions/element-radio-group",
                    "options":{
                        "label":"Wrap as gift?",
                        "items":[
                            {
                                "value":"yes",
                                "label":"Yes"
                            },
                            {
                                "value":"no",
                                "label":"No"
                            }
                        ]
                    }
                },
                "block_key_info":{
                    "$ref":"#/definitions/element-text",
                    "options":{
                        "value":"Thank you for using the cake ordering app!"
                    }
                }
            }
        },
        "actions":{
            "type":"object",
            "properties":{
                "cancel_action":{
                    "$ref":"#/definitions/action-secondary",
                    "options":{
                        "label":"Cancel",
                        "handler":"cancel"
                    }
                },
                "submit_action":{
                    "$ref":"#/definitions/action-primary",
                    "options":{
                        "label":"Save",
                        "handler":"request"
                    }
                }
            }
        }
    }
}


Embedded action's data exchange on opening the modal


The user flow interaction will go as follows for the Embedded app action:

  1. The User opens the three-dot/actions menu and clicks on the “New cake order“ action.
  2. A modal appears based on the JSON schema added to the Marketplace Manager for the Embedded action.
  3. Initial request will be sent to the endpoint that was set as an API endpoint in Marketplace Manager.

All requests from embedded actions contain the same query parameters as Basic app actions - resource, view, userId, companyId, selectedIds plus additional form, invoker (see Component library), and token (encrypted JWT token value). token contains encrypted userID and companyID, so you can verify them from the query parameters.

The response to the initial request should be formatted accordingly to the JSON schema data structure that was uploaded in Marketplace Manager.

The response for the initial request can be used for:

  • Simply acknowledging the request,
  • Setting default values for the inputs

For example, the response for a schema could be as follows. The response can partially include options for dynamic data such as "items" and "value" for different Blocks. The options will be merged with uploaded structure by block key defined in the schema and used in API response in the path /data/blocks or /data/actions.

{
    "data": {
        "blocks": {
            "block_key_delivery_method": {
                "value": 1,
                "items": [
                    {
                        "label": "Standard",
                        "value": 1
                    },
                    {
                        "label": "Accelerated",
                        "value": 2
                    }
                ]
            },
            "block_key_is_gift": {
                "value": "yes"
            }
        },
        "actions": {}
    }
}

The schema will now show the "standard" delivery option as a preselected value for Select Block and "yes" as a preselected value for Radio Group Block.

Or the response could be returned with a "data" property, that is required, and the "blocks" array and "actions" array can be left empty, as the response will be merged with the already added schema definition in Marketplace Manager and displayed as it is.

Response from the API endpoint

{
    "data": {
        "blocks": {},
        "actions": {}
    }
}

Here you can see, how the modal remained the same as in the schema definition, no new values were added.

Please note that options from the uploaded structure and API response will be first merged and then validated altogether (see Structure validation).


Schema structure validation


The response structure received from the app’s API endpoint can be incorrect. For example, this can happen when some options have an invalid value, a missing required option or, a Block that includes an unknown additional option. In this situation, the user will see an error.

For example, the following data response will cause validation errors as willNotPass is an invalid option`

{
    "data":{
        "blocks":{
            "input_item":{
                "willNotPass":true
            }
        },
        "actions":{
            "submit":{
                "handler":"invalid-handler"
            }
        }
    }
}
Modal validation error displayed in the modal UI

Modal validation error displayed in the modal UI

Actual errors won't be visible for users in the UI but can be checked in the Network tab in Developer Tools in your browser when you click on the error path.

If there is an error, troubleshooting can be done using the following parameters:

  • dataPath tells what Block's data is invalid.
  • message contains an explanation of why it is invalid.
  • params gives more context about the error.
Troubleshooting errors in the Network tab under Developer Tools in your browser tab.

Troubleshooting errors in the Network tab under Developer Tools in your browser tab.


Schema data exchange on modal form submit


Your own destination URL can be defined in the uploaded schema for each primary action button. By default, the Embedded app action URL set in Marketplace Manager will be used for all requests.

When all required fields are filled in, the user can submit the modal form (or open a new browser tab - depends on your action handler configuration).
Before sending the form data as a request payload, it will be collected from:

  • All visible Blocks
  • Blocks with “visibleOn”: “never”. These blocks won’t be visible to the users but allow you to send additional metadata to your service, e.g., data from fields of Pipedrive entities to save additional API requests.
{
    "block_key_input": "Some text value"
}

There are few options for the following user behavior:

  • in a positive scenario, the modal will be either closed with a snackbar notification shown to the user or a new browser tab will be opened (see Displaying success message).
  • in a negative scenario, there are 3 different ways how errors and error messages can be displayed to the user (see Displaying error message).

Updated 11 days ago


Embedded app actions


Suggested Edits are limited on API Reference Pages

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