API v1 documentation

https://api.pipedrive.com/v1

This documentation helps you implement the RESTful Pipedrive API v1. This API uses a JSON format for output and is capable of handling CORS (Cross-Origin Resource Sharing) requests. The API is stateless – all requests are validated against an API token. The API token can be obtained manually from the Pipedrive app, or via fetching the Authorations objects (documented below).

Warning:

URL Naming

The API uses a straight-forward URL naming convention. Each request must be made to the API endpoint (https://api.pipedrive.com/v1), followed by the type of object in a plural form, e.g. https://api.pipedrive.com/v1/deals. When one item is being asked and such method exists, the ID of the item must be appended to the URL, e.g. https://api.pipedrive.com/v1/deals/2, and when asking for sub-objects of an object, append that to the ID of the master object, e.g. https://api.pipedrive.com/v1/deals/2/activities. API token must be provided as part of the query string for all requests, using the 'api_token' variable, e.g. https://api.pipedrive.com/v1/deals/2?api_token=tS5adsXC6V2nH991


Response Format

Each response sent from the API contains a 'success' parameter which is of boolean type, indicating whether the request was carried out or not. Upon success being false, an optional 'error' parameter (string) may be given. In case of success being true, the response is always contained within a 'data' parameter, and an additional metadata may be carried inside an 'additional_data' parameter. You can use 'pretty_output=1' parameter in the GET-arguments to ask for an indented response — however using the pretty output in an actual integration is strongly discouraged as it is intended for debugging purposes and gets served slower.


Pagination and Lists

Most of the lists/item collections are paginated. The parameters that control the pagination are 'start' and 'limit', indicating the desired offset and the items per page values. Within the response's 'additional_data' object, a 'pagination' object will be set upon pagination. The 'additional_data.pagination' will contain the given start and limit, as well as 'more_items_in_collection' flag, indicating whether there are more items that can be fetched after the current batch. When there are, 'next_start' will also be set which can be used for next offset pointer.


"How can I fetch all deals/people/organizations/etc?"

While there are more efficient ways of accessing data than fetching all items — such as searching by name or filtering — you can, however, fetch all items of any kind from the Pipedrive API. In order to fetch all deals (or any other listable items, really), you can use the pagination data of lists responses to issue multiple requests in a loop to fetch all deals. You would have to check the 'additional_data.pagination.more_items_in_collection' flag in the response, and issue an additional request — only increasing the 'start' property by the given 'limit'. For example, if your first request ran against &start=0&limit=50, you would have to make the next request with &start=50&limit=50 to get the next 50 items, and continue making requests until the 'more_items_in_collection' flag is false in the response.


Custom fields

Each Deal, Person, Organization and Product can contain custom fields which are part of the dataset. All custom fields are referenced to as 40-character hashes in the dataset (e.g. dcf558aac1ae4e8c4f849ba5e668430d8df9be12). These custom fields are not shown in this API documentation (as they differ for each Pipedrive account) but they can be used in the requests when adding new items, or updating existing ones. For example, you may add a new deal by making a POST request to /deals with the following request body: { "title": "New deal with a custom field", "value": 500, "currency": "USD", "dcf558aac1ae4e8c4f849ba5e668430d8df9be12": "This is a custom field value" }. Each custom field type corresponds to a specific data format. To determine in which format you need to submit data into a custom field, make a GET request for the same kind of object and check the format of the value of that field.


Request format

We recommend using JSON body format when performing API requests. In order to do a proper JSON-formatted request, make sure you provide Content-Type: application/json as part of your HTTP request. Regular form-encoded body format is also supported but you may experience quirks related to lack of data types.


Field selector

You can pass in a field selector to indicate which fields you would like to fetch per each object when asking for a collection/list of objects. For example, you may only want to fetch deal's ID, title, value and currency when asking the deals list. This can be done by using the following syntax: GET https://api.pipedrive.com/v1/deals:(id,title,value,currency)?api_token=YOUR_API_TOKEN



The API endpoints & live testing