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.

Component library

Let's get started on combining the schema for your modal. The main gist is that the Embedded action consists of a modal combined from components which are Blocks and Action buttons.
On this page, we'll cover all Block types, how to add the Blocks, and possible relationships between different Blocks that can be used for the embedded app actions.

You can see how all Block types and Action buttons will look like when added to the modal in the following image.

The structure of the modal

The structure of the modal

Blocks


Blocks are smaller UI elements that can be customized for your app and its use cases. The Blocks are displayed inside the modal component, and each modal can have a maximum of 10 Blocks. In the limitation of 10, the primary and secondary Action buttons, as well as the modal header, are not included.

To combine the modal from Blocks and define its behavior, you'll need to add a JSON schema to Marketplace Manager. For the whole schema structure, see Embedded app actions.

To add a Block to the modal, first, you'll need to add the appropriate Block key and type. Block key should be unique to the Block and it'll be used to map out all relationships between Blocks and requests' data payloads. Block type needs to be added to the schema as $ref property from the list of available definitions:

  • #/definitions/element-text
  • #/definitions/element-input
  • #/definitions/element-select
  • #/definitions/element-datepicker
  • #/definitions/element-radio-group
  • #/definitions/element-checkbox-group
  • #/definitions/element-separator
  • #/definitions/element-textarea

This is how your modal will look like with just one input block defined where the block key is "block_key_1" and it is followed by the block type "$ref": "#/definitions/element-input":

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_1":{
                    "$ref":"#/definitions/element-input",
                    "options":{
                        "type":"text",
                        "placeholder":"Name",
                        "label":"Name",
                        "value":"John",
                        "allowClear":true,
                        "isRequired":true,
                        "visibleOn":{
                            "block_key_2":{
                                "equals":"task"
                            }
                        }
                    }
                }
            }
        }
    }
}

Commonly available options for the block

visibleOn

This option allows the modal to change its appearance - layout and default values of Blocks - depending on the choice a user has made with one Block. visibleOn option is available for all Blocks except the separator Block. visibleOn can control the visibility of a Block depending on another item’s value or the visibility of a whole Block. visibleOn can be added to the options of a Block, the item of a Block and Action buttons.

When visibleOn is added to be dependent on item values inside other Blocks, it supports 3 rules: not_empty, equals, and includes. These rules have to be used together with the Block key, where the rule has to be applied. For example, when visibleOn is added to an Input Block with the following criteria seen in the code sample below, the Input Block will become visible only when the "block_key_checkbox" value is exactly equal to "vanilla".

  • "block_key": "not_empty" expects any value in a Block, available for Blocks requiring inputs.
  • "block_key": {"equals": "on"} expects very specific value on to be selected, available for Blocks with toggle items.
  • "block_key": {"includes": "example"} expects text and inputs in Block value to contain a certain text.
{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_checkbox":{
                    "$ref":"#/definitions/element-checkbox-group",
                    "options":{
                        "label":"Flavors",
                        "value":[
                            "vanilla"
                        ],
                        "items":[
                            {
                                "value":"vanilla",
                                "label":"Vanilla"
                            },
                            {
                                "value":"chocolate",
                                "label":"Chocolate"
                            }
                        ]
                    }
                },
                "block_key_input":{
                    "$ref":"#/definitions/element-input",
                    "options":{
                        "type":"text",
                        "placeholder":"Insert size",
                        "label":"Cake size",
                        "value":"S",
                        "allowClear":true,
                        "isRequired":true,
                        "visibleOn":{
                            "block_key_checkbox":{
                                "equals":"vanilla"
                            }
                        }
                    }
                }
            }
        }
    }
}

visibleOn supports two extra rules for when there is a need to control the entire visibility of the entire Block. These rules specify if the Block should never be visible to the user or is always visible to the user. The Block’s value will be sent on action data submission after the click on Action button.

visibleOn: “never“ - the never rule can be used to hide a Block from the modal.

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_input":{
                    "$ref":"#/definitions/element-input",
                    "options":{
                        "label":"Hidden",
                        "value":"my hidden value",
                        "visibleOn":"never"
                    }
                }
            }
        }
    }
}

visibleOn: “always“ - the always rule can be used in case there is a need to reset previously set rules. In this sample, the Input Block will be displayed only when the Radio Block’s value is equal to yes.

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_input":{
                    "$ref":"#/definitions/element-input",
                    "options":{
                        "label":"Visible",
                        "value":"some visiblity value",
                        "visibleOn":{
                            "block_key_radio":{
                                "equals":"yes"
                            }
                        }
                    }
                },
                "block_key_radio":{
                    "$ref":"#/definitions/element-radio-group",
                    "options":{
                        "label":"Wrap as a gift?",
                        "value":"wrapping",
                        "items":[
                            {
                                "value":"yes",
                                "label":"Yes"
                            },
                            {
                                "value":"no",
                                "label":"No"
                            }
                        ]
                    }
                }
            }
        }
    }
}

Response from the API endpoint
Allows overriding set values in the schema with the data in the response structure.

{
    "data":{
        "blocks":{
            "block_key_input":{
                "visibleOn":"always"
            }
        },
        "actions":{
            
        }
    }
}


fetchOnChange

This option allows the modal to re-fetch data when the user has made a choice or an action. In general fetchOnChange is useful when a base value change needs to accommodate different values (or any other Block options) in other Blocks. fetchOnChange option is available for all Blocks, except the Text Block and Separator Block and can be added to Block together with other options.

In this example, when the date field’s value is changed, only one value for the delivery is provided.

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_datepicker":{
                    "$ref":"#/definitions/element-datepicker",
                    "options":{
                        "label":"Delivery date",
                        "value":"2021-03-17",
                        "message":"Cakes will be ready by 12:00 on selected date",
                        "placeholder":"Date",
                        "allowClear":true,
                        "isRequired":true,
                        "fetchOnChange":true
                    }
                },
                "block_key_select":{
                    "$ref":"#/definitions/element-select",
                    "options":{
                        "label":"Delivery method",
                        "message":"Please, specify how the delivery will be done.",
                        "placeholder":"Select method",
                        "isRequired":true
                    }
                }
            }
        }
    }
}

Response from the API endpoint
The response sets what value of the Select Block will be available for the set date by changing the available item options. The response can also be the same as for the initial request.

{
    "data":{
        "blocks":{
            "block_key_select":{
                "items":[
                    {
                        "label":"Standard",
                        "value":1
                    }
                ]
            }
        },
        "actions":{
            
        }
    }
}

After the user changes the value in the Datepicker Block, it will make the same request as the initial request to fetch data for action. And it will include additional query params:

  • form serialized JSON with current form state
  • invoker key of changed block

This is how the URL will look like when additional parameters are added:
https://example.org?resource=deal&view=details&...&form=%7B%22block?key?select%22%3A%22label%22%2C%22standard%22%3value%221%22%7D&invoker=datepicker


Text


Text Block allows displaying contextual messages or explanations inside the modal.

Options for adding a Text Block:

Name
Type
Sample values

value

REQUIRED
string

Thank you for using the cake ordering app!

markdown

boolean

Supported markdown types:
heading (# text),
paragraph,
strong (** text **),
link ([text](url)),
blockquote ( > text),
list (1. text),
bullets (-)

visibleOn

array of objects

For the heading type, only one format of headings is supported. All other formats will be displayed the same way.

Example schema for Text Block

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_text":{
                    "$ref":"#/definitions/element-text",
                    "options":{
                        "markdown":true,
                        "value":"# Contact info \n For any other info regarding **your order** contact us through our [website](https://cake-demo-app.vercel.app/).\nOur help desk is working: \n 1. Monday - Friday 9am-4pm \n 2. Saturdays 10am-2pm \n\nOur stores are in: \n - Siberia\n - Malibu beach \n > Enjoy your cake!"
                    }
                }
            }
        }
    }
}


Input


Input is used to accept data from the user.

Input Block with an error message

Input Block with an error message

Input Block with a set value

Input Block with a set value

Options for adding an Input Block:

Name
Type
Description
Sample values

label

REQUIRED
string

Label is displayed above the input field. It should be used to specify what type of input is expected to be inserted by the user.

Cake size

type

string

The type of the input that should be added by the user.

Type needs to be one of "text", "email", "number", "password", "search", "url")

password formats user input in a hidden bulleted list.

search allows user to enter search queries into. These fields are functionally identical to text inputs, but are styled differently.

URL requires a URL as the value of the input.

value

string

The value displayed in the input box. Can be either set as a default value by the app or a new one added by the user.

M

placeholder

string

The placeholder text displayed when no input value has been added

Insert size

message

string

An additional message placed below the input in a text format.

Cake size can be either S, L or M.

allowClear

boolean

Allows clearing the input. To clear the input field, the user will have to click the "x" at the end of the input box.

true, false

isRequired

boolean

Makes the field mandatory to be filled by the user.

true, false

visibleOn

array of objects

fetchOnChange

array of objects

error

string

Input Block can also display an error message when the data inserted by the user doesn't match a set criteria. See the expected error page on how to set this up.

Example schema for the Input Block

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_input":{
                    "$ref":"#/definitions/element-input",
                    "options":{
                        "type":"text",
                        "placeholder":"Insert size",
                        "label":"Cake size",
                        "value":"M",
                        "message":"Cake size can be either S, M or L",
                        "allowClear":true,
                        "isRequired":true
                    }
                }
            }
        }
    }
}


Select


Select Block can be used to show the user multiple options from a dropdown list from which they can choose one item.

Options for adding a Select Block:

Name
Type
Description
Sample values

label

REQUIRED
string

Label is displayed above the Select Block's options. It should be used to specify what the user is selecting.

Delivery method

value

string/boolean/number or array of string/boolean/number

Value can be used to set an already chosen default item or a value chosen by the user.

Dependent on the chosen type.

message

string

An additional guiding message in a text format.

Please, specify how the delivery will be done.

placeholder

string

The placeholder text displayed when no input value has been added

Select method

allowClear

boolean

Allows clearing the selected option. To clear the field, the user will have to click the "x" at the end of the input box.

true, false

isRequired

boolean

Makes the field mandatory to be filled by the user.

true, false

filter

boolean

Allows to filter available items in the dropdown by term.

true, false

fetchOnChange

array of objects

error

string

items

array of objects

See the following table

See the following table

Items structure:
The items element must contain the following 4 objects from which the first 2 are required. visibleOn can be added either to the item or Block, depending on your use-case.

Name
Type
Description
Sample values

label

REQUIRED
string

The naming of the item.

Standard

value

REQUIRED
string/boolean/number

Uniquely set value for an item.

Dependent on the chosen type.

isDisabled

boolean

Disables the item from being selected.

true, false

visibleOn

array of objects

Example schema for the Select Block

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_select":{
                    "$ref":"#/definitions/element-select",
                    "options":{
                        "label":"Delivery method",
                        "message":"Please, specify how the delivery will be done.",
                        "placeholder":"Select method",
                        "isRequired":true,
                        "items":[
                            {
                                "label":"Standard",
                                "value":1
                            },
                            {
                                "label":"Accelerated",
                                "value":2
                            }
                        ]
                    }
                }
            }
        }
    }
}


DatePicker


DatePicker allows users to select a set date from the calendar view.

Options for adding a DatePicker Block:

Name
Type
Discription
Sample values

label

REQUIRED
string

Label is displayed above the Datepicker Block. It should be used to specify what date should be selected.

Delivery date

value

string

The value of the datepicker. It can be sent as a default date or the one selected by the user.

The format should be YYYY-MM-DD
Example: 2021-02-17

message

string

An additional guiding message in a text format.

Cakes will be ready by 12:00 on the selected date.

error

string

An error message displayed under the Datepicker box. See Expected error handling on how to set it up.

Please select a non-holiday date.

allowClear

boolean

Allows clearing the selected date. To clear the box, the user will have to click the "x" at the end of the box.

true, false

isRequired

boolean

Makes the field mandatory to be filled by the user.

true, false

visibleOn

array of objects

fetchOnChange

array of objects

Example schema for the Datepicker Block

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_datepicker":{
                    "$ref":"#/definitions/element-datepicker",
                    "options":{
                        "label":"Delivery date",
                        "value":"2021-02-17",
                        "message":"Cakes will be ready by 12:00 on selected date",
                        "placeholder":"Date",
                        "allowClear":true,
                        "isRequired":true
                    }
                }
            }
        }
    }
}


Radio Group


Allows selecting one item from a displayed bulleted list.

Options for adding a Radio Group Block:

Name
Type
Description
Sample values

label

REQUIRED
string

Label is displayed above the Radio Group Block. It should be used to specify what should be selected by the user.

Wrap as a gift?

value

string

The value of the radio group.

yes

items

array of objects

See the following table

See the following table

isRequired

boolean

Makes the field mandatory to be filled by the user.

true,false

message

string

An additional guiding message in a text format.

error

string

An error message displayed under the radio group box. See Expected errors on how to set it up.

fetchOnChange

array of objects

Items structure:
The items element must contain the following 4 objects from which the first 2 are required. visibleOn can be added either to the item or Block, depending on your use-case.

Name
Type
Description
Sample values

label

REQUIRED
string

The naming of the item.

Yes, No

value

REQUIRED
string

Uniquely set value for an item.

Dependent on the chosen type.

isDisabled

boolean

Disables the item from being selected.

true, false

visibleOn

array of objects

Example schema for Radio Group Block

In this example, we have also shown how to add the visibleOn common option. In this case, the Radio group Block will not display the maybe option item to the user as they have previously selected the cake to be a vanilla cake, as the fictional store we use doesn't offer gift wrapping for cakes made of vanilla (let's go with this for the sake of the example, in the real world, it'd be awesome if all cakes could always be wrapped as gifts!).

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_radio":{
                    "$ref":"#/definitions/element-radio-group",
                    "options":{
                        "label":"Wrap as a gift?",
                        "value":"wrapping",
                        "items":[
                            {
                                "value":"yes",
                                "label":"Yes"
                            },
                            {
                                "value":"no",
                                "label":"No"
                            },
                            {
                                "value":"hidden",
                                "label":"Maybe",
                                "visibleOn":{
                                    "block_key_checkbox":{
                                        "equals":"vanilla"
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        }
    }
}


Checkbox Group


Blue checkboxes allow selecting items in a list view. All items or none can also be selected.

Options for adding a Checkbox Group Block:

Name
Type
Description
Sample values

label

string

The label is displayed above the Checkbox Group Block. It should be used to specify what should be selected by the user.

Flavors

value

array of string

The value of the Checkbox group.

items

array of objects

See the following table

See the following table

isRequired

boolean

Makes the field mandatory to be filled by the user.

true, false

message

string

An additional guiding message in a text format.

fetchOnChange

array of objects

error

string

See Expected errors on how to set it up

See Expected errors on how to set it up

Items structure:
The items element must contain the following 4 objects from which the first 2 are required. visibleOn can be added either to the item or Block, depending on your use-case.

Name
Type
Description
Sample values

label

REQUIRED
string

The naming of the item.

Vanilla

value

REQUIRED
array of string

Uniquely set value for an item.

Dependent on the chosen type.

isDisabled

boolean

Disables the item from being selected.

true, false

visibleOn

array of objects

Example schema for the Checkbox Group Block

In this example, we provide three items to be selected in the Checkbox Group Block. From those three, the possibility to choose the chocolate-flavored cake is disabled. If the input, aka the cake size in this example, includes "L", the checkbox option item hidden_option value will be hidden.

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_checkbox":{
                    "$ref":"#/definitions/element-checkbox-group",
                    "options":{
                        "label":"Flavors",
                        "value":[
                            "cranberry"
                        ],
                        "items":[
                            {
                                "value":"vanilla",
                                "label":"Vanilla"
                            },
                            {
                                "value":"chocolate",
                                "label":"Chocolate",
                                "isDisabled":true
                            },
                            {
                                "value":"cranberry",
                                "label":"Cranberry"
                            },
                            {
                                "value":"hidden_option",
                                "label":"Not visible",
                                "visibleOn":{
                                    "block_key_input":{
                                        "includes":"L"
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        }
    }
}


Separator


Separator Block allows displaying a thin grey line between other Blocks to visually separate the modal into sections.

For adding the Separator Block, add the following code to your schema (for a larger schema, start from the "type" parameter that is after the "blocks" parameter).

Example schema for the Separator Block

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_separator":{
                    "$ref":"#/definitions/element-separator"
                }
            }
        }
    }
}


Textarea


Allows adding a text area for larger comments and texts.

Options for adding a Textarea Block:

Name
Type
Description
Sample values

label

REQUIRED
string

Label is displayed above the Textarea box. It should be used to specify what type of input is expected to be inserted by the user.

Additional instructions

value

string

The value displayed in the textarea box.

placeholder

string

The placeholder text displayed when no text has been added. This can be used to give a hint to users on what info they need to add.

Write "Happy birthday!" on the cake

message

string

An additional message placed below the textarea box in a text format.

What would you like to have on your cake?

resize

boolean

Allows to resize the Textarea field.

true, false

isRequired

boolean

Makes the field mandatory to be filled by the user.

true, false

visibleOn

array of objects

error

string

An error message displayed under the textarea. See Expected errors on how to set it up.

An error message displayed under the textarea. See Expected errors on how to set it up.

Example schema for the Textarea Block

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_textarea":{
                    "$ref":"#/definitions/element-textarea",
                    "options":{
                        "placeholder":"Write Happy birthday! on the cake",
                        "label":"Additional instructions",
                        "value":"Long text",
                        "message":"What would you like to have on your cake?",
                        "resize":true,
                        "isRequired":true
                    }
                }
            }
        }
    }
}


Action buttons


Action buttons are displayed in the modal footer of an Embedded app action. They are clickable and will trigger saving, resetting, or cancellations of the modal. Each modal has to have a minimum of one and a maximum of two action buttons. Available action buttons have two types - primary and secondary actions. The primary action will be displayed as a green UI button and secondary as a grey UI button.

Adding an action button is similar to adding a Block. First, you'll need to add the action key and action type as a $ref property from the following two:

  • #/definitions/action-primary
  • #/definitions/action-secondary


Primary Action button

The primary action button will be activated once all required Blocks are filled and depending on the handler option will:

  • send a POST HTTP request with form data that the user filled in the action modal as body payload ("handler": "request");
  • open a new browser tab with data that the user filled in action modal as serialized JSON in form of query parameters ("handler": "open-url").

By default URL link will be used as the destination endpoint for all requests, but it can be also overwritten with the URL option by uploading schema with it.

Options for primary Action button

Name
Type
Description
Sample values

label

REQUIRED
string

Descriptive name of the action button, showcasing what will happen on button click.

e.g. submit or Create in app"

handler

REQUIRED
string

Option value will determine what the button will do when user clicks it.

one of "request", "open-url".

url

string

Must be added only when "handler": "open-url" and there is a need to direct the user out of Pipedrive to see the outcome of the embedded action inside the app.
If "handler": "open-url" is selected but url is not added to the schema, default URL for the app (the one added in Marketplace Manager for Embedded action) will be used.

Example schemas for primary action button

Send POST HTTP request

{
	"type":"object",
	"properties":{
		"actions":{
			"type":"object",
			"properties":{
				"submit":{
					"$ref":"#/definitions/action-primary",
					"options":{
						"label":"Submit",
						"handler":"request"
					}
				}
			}
		}
	}
}

Open a new tab with action modal

{
	"type":"object",
	"properties":{
		"actions":{
			"type":"object",
			"properties":{
				"create":{
					"$ref":"#/definitions/action-primary",
					"options":{
						"label":"Create in Asana",
						"handler":"open-url"
					}
				}
			}
		}
	}
}

Open new tab with custom URL

{
	"type":"object",
	"properties":{
		"actions":{
			"type":"object",
			"properties":{
				"create":{
					"$ref":"#/definitions/action-primary",
					"options":{
						"label":"Create in app",
						"handler":"open-url",
						"url":"https://www.exampleURLtoapp.com"
					}
				}
			}
		}
	}
}


Secondary Action button

The secondary action button allows the user to either reset all the contents of the modal to the original ones defined in the schema (added in the Marketplace Manager) or cancel and close the modal, therefore canceling the whole embedded app action.
For adding the secondary action button you'll need to add the following options to the schema:

Name
Type
Description
Sample values

label

REQUIRED
string

Descriptive name of the action button, showcasing what will happen on button click.

"Reset", "Cancel and Close"

handler

REQUIRED
string

Option value will determine what the button will do when user clicks it.

One of "reset" or "cancel"

Reset form to an initial state

{
	"type":"object",
	"properties":{
		"actions":{
			"type":"object",
			"properties":{
				"action_reset":{
					"$ref":"#/definitions/action-secondary",
					"options":{
						"label":"Reset",
						"handler":"reset"
					}
				}
			}
		}
	}
}

Cancel and close modal

When the user clicks this action, the modal will be closed, and the action canceled.

{
	"type":"object",
	"properties":{
		"actions":{
			"type":"object",
			"properties":{
				"action_cancel":{
					"$ref":"#/definitions/action-secondary",
					"options":{
						"label":"Cancel and close",
						"handler":"cancel"
					}
				}
			}
		}
	}
}

Updated 6 days ago


Component library


Suggested Edits are limited on API Reference Pages

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