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.

User interaction handling

Your modal for Embedded app action can encounter different scenarios when a user interacts with it. A modal should be able to show the following depending on the usage scenario:

  • A success message on completion of an action,
  • Error message when data loading from the schema fails,
  • Validation error message if input values are incorrect,
  • Global modal error if requests from modal to app fail.


Displaying success message


If the received data about the Blocks is correct, the app should return the following structure to finish the user interaction flow and give a corresponding notice to the user.

  • snackbar - shows message in the bottom left corner of the page.
    • message - (string) Additional message for the user.
    • type - (string) value must be “snackbar”.
    • link - (object) Not required, but provides a way to add an external link to the success message.
      • label - (string) Label of the linked item.
      • value - (string) Value of the linked item in a URL format.

Example of a response from your app when showing a success:

status code: 200

{
    "success": {
        "message": "Successfully done",
        "type": "snackbar",
        "link": {
            "label": "View item",
            "value": "https://marketplace.pipedrive.com"
        }
    }
}
Success message in a snackbar format

Success message in a snackbar format


Displaying error messages


Initial Data loading


Data loads after a user has clicked on an embedded app action and the modal is opened. First, the UI of the modal will show a spinner loading, during which the click will trigger a GET request to retrieve the data from the API endpoint set in Marketplace Manager for the Embedded action. We also check if the user has the permissions to access the app and action. Afterward, the data will be fetched from your API and mapped it to the schema.

If the request fails, a global error message is displayed inside the modal.

Initial data load error displayed in the modal

Initial data load error displayed in the modal

Common reasons why the request may fail:

  • The user who triggered the action doesn't have permission to do so (the app is not installed).

  • The response structure from the app's API endpoint is invalid.

  • The response data structure doesn't match with the app's uploaded schema structure.

  • The request to the app's API endpoint took more than 10 seconds to return a response.

Example of failure response from Pipedrive

For example, if a Block with the type set as #/definitions/element/text has unknown property items, then the response from Pipedrive describes the error with paths to the wrong Block. See more about troubleshooting in the Structure validation section.

{
    "success": false,
    "error": "The response from the server is not according to the structure",
    "data": {
        "errors": [
            {
                "keyword": "additionalProperties",
                "dataPath": "/data/blocks/text_item",
                "schemaPath": "#/additionalProperties",
                "params": {
                    "additionalProperty": "items"
                },
                "message": "should NOT have additional properties"
            }
        ],
        "response": {
            "data": {
                "blocks": {
                    "block_key_text": {
                        "items": []
                    }
                },
                "actions": {}
            }
        }
    }
}

Unauthorized access screen

When there has been an error in the app authorization a “Connection lost” message can be displayed, guiding the user to reinstall the app.

For this screen to be displayed in the modal, an HTTP status code 401 must be sent with any response body on the initial data request. The green button, asking users to reinstall, will use the redirect URL defined in Marketplace Manager, and by clicking it, users will be directed to the OAuth authorization page of the app.


User interface


When the modal form's data has been successfully loaded from the app, and a user submits an action from the bottom action buttons, we make a POST request to send the data from the modal form to the app's API endpoint.

Expected errors

This error can be displayed inside the modal to any Block requiring any user input (Input, Select, Datepicker, Textarea, Radio Group, Checkbox Group Blocks) when an app has received data inserted by a user and identified it as invalid. The error message will indicate to the user that the input is either wrong or formatted incorrectly.

The expected error displayed for incorrect contents in the Input block

The expected error displayed for incorrect contents in the Input block

To display the error messages, the app needs to respond with the following structure. In the response, when sending the error message, don't include the items property in the Blocks with dynamic content, otherwise previously set item's values will be overwritten.

Example of response structure with Input Block error:

{
  "data": {
    "blocks": {
      "block_key_input_email": {
        "label": "Input label",
        "value": "Input content",
        "message": "info",
        "error": "error"
      }
    }
  }
}

Expected errors - Global error

If the app fails to handle a submitted request from the Embedded action's modal but the cause of the failure is not connected to any of the inserted inputs, the app can respond with a 400 HTTP status code and include a custom error message body.

An expected error message displayed in the modal

An expected error message displayed in the modal

For that error, the modal must receive a response with the following structure. The message parameter must be in a string format and must have a helpful, contextual, and actionable error message that the users will understand to act upon.

Response from the API endpoint

{
  "error": {
    "message": "Message body"
  }
}


Unexpected error


When the app fails to handle the request with an unexpected error, and therefore any meaningful message can’t be displayed, then the default message will be shown in the modal.

Unexpected error: 
Something went wrong, please try again.

Unexpected error:
Something went wrong, please try again.

Known reasons for this error appearing:

  • The response from the app has an invalid structure. The structure doesn’t match with the Input or Global error structure described above.
  • The request to the app took more than 10 seconds.
  • The request to Pipedrive failed due to Server Error.

Updated 4 months ago


User interaction handling


Suggested Edits are limited on API Reference Pages

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