Skip to content

Instantly share code, notes, and snippets.

@MarcelloTheArcane

MarcelloTheArcane/schema.json

Last active August 28, 2024 13:32
Show Gist options
  • Save MarcelloTheArcane/12764b13be3192a000c62bd9e40a0ebc to your computer and use it in GitHub Desktop.
Save MarcelloTheArcane/12764b13be3192a000c62bd9e40a0ebc to your computer and use it in GitHub Desktop.
Download ZIP
Pipedrive Schema
Raw
schema.json
[
{
"heading": "Activities",
"description": "Activities are appointments/tasks/events on a calendar that can be associated with a Deal, a Person and an Organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular User. Note that activities can also be created without a specific date/time.",
"endpoint": [
[
{
"method": "GET",
"url": "/activities",
"summary": "Returns all activities assigned to a particular user.",
"parameters": [
{
"key": "user_id",
"description": "ID of the user whose activities will be fetched. If omitted, the user associated with the API token will be used. If 0, activities for all company users will be fetched based on the permission sets.",
"type": "number"
},
{
"key": "filter_id",
"description": "ID of the filter to use (will narrow down results if used together with user_id parameter).",
"type": "number"
},
{
"key": "type",
"description": "Type of the activity, can be one type or multiple types separated by a comma. This is in correlation with the key_string parameter of ActivityTypes.",
"type": "string"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "start_date",
"description": "Date in format of YYYY-MM-DD from which activities to fetch from.",
"type": "date"
},
{
"key": "end_date",
"description": "Date in format of YYYY-MM-DD until which activities to fetch to.",
"type": "date"
},
{
"key": "done",
"description": "Whether the activity is done or not. 0 = Not done, 1 = Done. If omitted returns both Done and Not done.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "GET",
"url": "/activities/{id}",
"summary": "Returns details of a specific activity.",
"parameters": [
{
"key": "id",
"description": "ID of the activity",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/activities",
"summary": "Adds a new activity. Includes more_activities_scheduled_in_context property in response's additional_data which indicates whether there are more undone activities scheduled with the same deal, person or organization (depending on the supplied data). For more information on how to add an activity, see this tutorial.",
"parameters": [
{
"key": "subject",
"description": "Subject of the activity",
"type": "string"
},
{
"key": "done",
"description": "Whether the activity is done or not. 0 = Not done, 1 = Done",
"type": "enumerated",
"values": [
"0",
"1"
]
},
{
"key": "type",
"description": "Type of the activity. This is in correlation with the key_string parameter of ActivityTypes.",
"type": "string"
},
{
"key": "due_date",
"description": "Due date of the activity. Format: YYYY-MM-DD",
"type": "date"
},
{
"key": "due_time",
"description": "Due time of the activity in UTC. Format: HH:MM",
"type": "time"
},
{
"key": "duration",
"description": "Duration of the activity. Format: HH:MM",
"type": "time"
},
{
"key": "user_id",
"description": "ID of the user whom the activity will be assigned to. If omitted, the activity will be assigned to the authorized user.",
"type": "number"
},
{
"key": "deal_id",
"description": "ID of the deal this activity will be associated with",
"type": "number"
},
{
"key": "person_id",
"description": "ID of the person this activity will be associated with",
"type": "number"
},
{
"key": "participants",
"description": "List of multiple persons (participants) this activity will be associated with. If omitted, single participant from person_id field is used. It requires a structure as follows: [{\"person_id\":1,\"primary_flag\":true}]",
"type": "json string"
},
{
"key": "org_id",
"description": "ID of the organization this activity will be associated with",
"type": "number"
},
{
"key": "note",
"description": "Note of the activity (HTML format)",
"type": "string"
}
]
}
],
[
{
"method": "PUT",
"url": "/activities/{id}",
"summary": "Modifies an activity. Includes more_activities_scheduled_in_context property in response's additional_data which indicates whether there are more undone activities scheduled with the same deal, person or organization (depending on the supplied data).",
"parameters": [
{
"key": "id",
"description": "ID of the activity",
"type": "number"
},
{
"key": "subject",
"description": "Subject of the activity. When omitted, will remain unchanged.",
"type": "string"
},
{
"key": "done",
"description": "Whether the activity is done or not. 0 = Not done, 1 = Done",
"type": "enumerated",
"values": [
"0",
"1"
]
},
{
"key": "type",
"description": "Type of the activity. This is in correlation with the key_string parameter of ActivityTypes.",
"type": "string"
},
{
"key": "due_date",
"description": "Due date of the activity. Format: YYYY-MM-DD",
"type": "date"
},
{
"key": "due_time",
"description": "Due time of the activity in UTC. Format: HH:MM",
"type": "time"
},
{
"key": "duration",
"description": "Duration of the activity. Format: HH:MM",
"type": "time"
},
{
"key": "user_id",
"description": "ID of the user whom the activity will be assigned to",
"type": "number"
},
{
"key": "deal_id",
"description": "ID of the deal this activity will be associated with",
"type": "number"
},
{
"key": "person_id",
"description": "ID of the person this activity will be associated with",
"type": "number"
},
{
"key": "participants",
"description": "List of multiple persons (participants) this activity will be associated with. If omitted, single participant from person_id field is used. It requires a structure as follows: [{\"person_id\":1,\"primary_flag\":true}]",
"type": "json string"
},
{
"key": "org_id",
"description": "ID of the organization this activity will be associated with",
"type": "number"
},
{
"key": "note",
"description": "Note of the activity (HTML format). When omitted, will remain unchanged.",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/activities",
"summary": "Marks multiple activities as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated IDs that will be deleted",
"type": "array"
}
]
}
],
[
{
"method": "DELETE",
"url": "/activities/{id}",
"summary": "Deletes an activity.",
"parameters": [
{
"key": "id",
"description": "ID of the activity",
"type": "number"
}
]
}
]
]
},
{
"heading": "ActivityFields",
"description": "ActivityFields represent different fields that Activity has.",
"endpoint": [
[
{
"method": "GET",
"url": "/activityFields",
"summary": "Return list of all fields for activity",
"parameters": []
}
]
]
},
{
"heading": "ActivityTypes",
"description": "ActivityTypes represent different kinds of activities that can be stored. Each ActivityType is presented to the user with an icon and a name. Additionally, a color can be defined (not implemented in the Pipedrive app as of today). ActivityTypes are linked to Activities via ActivityType.key_string = Activity.type. The key_string will be generated by the API based on the given name of the ActivityType upon creation, and cannot be changed. ActivityTypes should be presented to the user in an ordered manner, using the ActivityType.order_nr value.",
"endpoint": [
[
{
"method": "GET",
"url": "/activityTypes",
"summary": "Returns all activity types",
"parameters": []
}
],
[
{
"method": "POST",
"url": "/activityTypes",
"summary": "Adds a new activity type, returns the ID, the key_string and the order number of the newly added activity type upon success.",
"parameters": [
{
"key": "name",
"description": "Name of the activity type",
"type": "string"
},
{
"key": "icon_key",
"description": "Icon graphic to use for representing this activity type.",
"type": "enumerated",
"values": [
"task",
"email",
"meeting",
"deadline",
"call",
"lunch",
"calendar",
"downarrow",
"document",
"smartphone",
"camera",
"scissors",
"cogs",
"bubble",
"uparrow",
"checkbox",
"signpost",
"shuffle",
"addressbook",
"linegraph",
"picture",
"car",
"world",
"search",
"clip",
"sound",
"brush",
"key",
"padlock",
"pricetag",
"suitcase",
"finish",
"plane",
"loop",
"wifi",
"truck",
"cart",
"bulb",
"bell",
"presentation"
]
},
{
"key": "color",
"description": "A designated color for the activity type in 6-character HEX format (e.g. FFFFFF for white, 000000 for black).",
"type": "string"
}
]
}
],
[
{
"method": "PUT",
"url": "/activityTypes/{id}",
"summary": "Updates an activity type.",
"parameters": [
{
"key": "id",
"description": "ID of the activity type",
"type": "number"
},
{
"key": "name",
"description": "Name of the activity type",
"type": "string"
},
{
"key": "icon_key",
"description": "Icon graphic to use. Supported values: default, call, meeting, lunch, email, task, deadline. Additional supported values will be made available in the future.",
"type": "enumerated string"
},
{
"key": "color",
"description": "A designated color for the activity type in 6-character HEX format (e.g. FFFFFF for white, 000000 for black).",
"type": "string"
},
{
"key": "order_nr",
"description": "An order number for this activity type. Order numbers should be used to order the types in the activity type selections.",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/activityTypes",
"summary": "Marks multiple activity types as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated activity type IDs to delete",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/activityTypes/{id}",
"summary": "Marks an activity type as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the activity type",
"type": "number"
}
]
}
]
]
},
{
"heading": "Authorizations",
"description": "Attention! As of December 2, 2019, we will be removing the Authorizations endpoints.",
"endpoint": [
[
{
"method": "POST",
"url": "/authorizations",
"summary": "We deprecated this endpoint on February 28, 2019, and we strongly advise you to avoid the use of this endpoint. The /authorizations endpoint is a legacy way of authorization using generic API keys. Such an approach does not provide transparency into which applications have access to data nor the opportunity to control the permissions these integrations have. Therefore we suggest using OAuth Authorization instead. In case you are using the /authorizations API endpoint in your code or 3rd party app/integration, please remove any dependency on this endpoint as soon as possible.",
"parameters": [
{
"key": "email",
"description": "Email of the user",
"type": "string"
},
{
"key": "password",
"description": "Password of the user",
"type": "string"
}
]
}
]
]
},
{
"heading": "Currencies",
"description": "Supported currencies which can be used to represent the monetary value of a Deal, or a value of any monetary type custom field. The Currency.code field must be used to point to a currency. Currency.code is the ISO-4217 format currency code for non-custom currencies. You can differentiate custom and non-custom currencies using the is_custom_flag property. For custom currencies, it is intended that the formatted sums are displayed in the UI using the following format: [sum][non-breaking space character][currency.symbol], for example: 500 users. Custom currencies cannot be added or removed via the API yet — rather the admin users of the account must configure them from the Pipedrive app.",
"endpoint": [
[
{
"method": "GET",
"url": "/currencies",
"summary": "Returns all supported currencies in given account which should be used when saving monetary values with other objects. The 'code' parameter of the returning objects is the currency code according to ISO 4217 for all non-custom currencies.",
"parameters": [
{
"key": "term",
"description": "Optional search term that is searched for from currency's name and/or code.",
"type": "string"
}
]
}
]
]
},
{
"heading": "Deals",
"description": "Deals represent ongoing, lost or won sales to an Organization or to a Person. Each deal has a monetary value and must be placed in a Stage. Deals can be owned by a User, and followed by one or many Users. Each Deal consists of standard data fields but can also contain a number of custom fields. The custom fields can be recognized by long hashes as keys. These hashes can be mapped against DealField.key. The corresponding label for each such custom field can be obtained from DealField.name.",
"endpoint": [
[
{
"method": "GET",
"url": "/deals",
"summary": "Returns all deals. For more information on how to get all deals, see this tutorial.",
"parameters": [
{
"key": "user_id",
"description": "If supplied, only deals matching the given user will be returned.",
"type": "number"
},
{
"key": "filter_id",
"description": "ID of the filter to use",
"type": "number"
},
{
"key": "stage_id",
"description": "If supplied, only deals within the given stage will be returned.",
"type": "number"
},
{
"key": "status",
"description": "Only fetch deals with specific status. If omitted, all not deleted deals are fetched.",
"type": "enumerated",
"values": [
"open",
"won",
"lost",
"deleted",
"all_not_deleted"
]
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page. Default limit is 100, maximum limit is 500.",
"type": "number"
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).",
"type": "string"
},
{
"key": "owned_by_you",
"description": "When supplied, only deals owned by you are returned. However filter_id takes precedence over owned_by_you when both are supplied.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "GET",
"url": "/deals/find",
"summary": "Searches all deals by their title.",
"parameters": [
{
"key": "term",
"description": "Search term to look for",
"type": "string"
},
{
"key": "person_id",
"description": "ID of the person deal is associated with.",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the organization deal is associated with.",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/summary",
"summary": "Returns summary of all the deals.",
"parameters": [
{
"key": "status",
"description": "Only fetch deals with specific status. open = Open, won = Won, lost = Lost",
"type": "enumerated",
"values": [
"",
"open",
"won",
"lost"
]
},
{
"key": "filter_id",
"description": "user_id will not be considered. Only deals matching the given filter will be returned.",
"type": "number"
},
{
"key": "user_id",
"description": "Only deals matching the given user will be returned. user_id will not be considered if you use filter_id.",
"type": "number"
},
{
"key": "stage_id",
"description": "Only deals within the given stage will be returned.",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/timeline",
"summary": "Returns open and won deals, grouped by defined interval of time set in a date-type dealField (field_key) — e.g. when month is the chosen interval, and 3 months are asked starting from January 1st, 2012, deals are returned grouped into 3 groups — January, February and March — based on the value of the given field_key.",
"parameters": [
{
"key": "start_date",
"description": "Date where first interval starts. Format: YYYY-MM-DD",
"type": "string"
},
{
"key": "interval",
"description": "Type of interval.\n\nday\nDay\nweek\nA full week (7 days) starting from start_date\nmonth\nA full month (depending on the number of days in given month) starting from start_date\nquarter\nA full quarter (3 months) starting from start_date",
"type": "enumerated",
"values": [
"day",
"week",
"month",
"quarter"
]
},
{
"key": "amount",
"description": "Number of given intervals, starting from start_date, to fetch. E.g. 3 (months).",
"type": "number"
},
{
"key": "field_key",
"description": "The name of the date field by which to get deals by.",
"type": "string"
},
{
"key": "user_id",
"description": "If supplied, only deals matching the given user will be returned.",
"type": "number"
},
{
"key": "pipeline_id",
"description": "If supplied, only deals matching the given pipeline will be returned.",
"type": "number"
},
{
"key": "filter_id",
"description": "If supplied, only deals matching the given filter will be returned.",
"type": "number"
},
{
"key": "exclude_deals",
"description": "Whether to exclude deals list (1) or not (0). Note that when deals are excluded, the timeline summary (counts and values) is still returned.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "totals_convert_currency",
"description": "3-letter currency code of any of the supported currencies. When supplied, totals_converted is returned per each interval which contains the currency-converted total amounts in the given currency. You may also set this parameter to 'default_currency' in which case users default currency is used.",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}",
"summary": "Returns details of a specific deal. Note that this also returns some additional fields which are not present when asking for all deals – such as deal age and stay in pipeline stages. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the 'key' value of dealFields. For more information on how to get all details of a deal, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}/activities",
"summary": "Lists activities associated with a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "done",
"description": "Whether to fetch done (1) or undone (0) activities. If omitted from request, both undone and done activities are fetched.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "exclude",
"description": "A comma-separated string of activity IDs to exclude from result",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}/files",
"summary": "Lists files associated with a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "include_deleted_files",
"description": "When enabled, the list of files will also include deleted files. Please note that trying to download these files will not work.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, product_id, add_time, update_time, file_name, file_type, file_size, comment.",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}/flow",
"summary": "Lists updates about a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}/followers",
"summary": "Lists the followers of a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}/mailMessages",
"summary": "Lists mail messages associated with a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}/participants",
"summary": "Lists participants associated with a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}/permittedUsers",
"summary": "List users permitted to access a deal",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "access_level",
"description": "If set, filter results by allowed access level. 1 = Read, 2 = Write, 3 = Read+Write",
"type": "enumerated",
"values": [
"",
"1",
"2",
"3"
]
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}/persons",
"summary": "Lists all persons associated with a deal, regardless of whether the person is the primary contact of the deal, or added as a participant.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/deals/{id}/products",
"summary": "Lists products attached to a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "include_product_data",
"description": "Whether to fetch product data along with each attached product (1) or not (0, default).",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "POST",
"url": "/deals",
"summary": "Adds a new deal. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys. To determine which custom fields exists, fetch the dealFields and look for 'key' values. For more information on how to add a deal, see this tutorial.",
"parameters": [
{
"key": "title",
"description": "Deal title",
"type": "string"
},
{
"key": "value",
"description": "Value of the deal. If omitted, value will be set to 0.",
"type": "string"
},
{
"key": "currency",
"description": "Currency of the deal. Accepts a 3-character currency code. If omitted, currency will be set to the default currency of the authorized user.",
"type": "string"
},
{
"key": "user_id",
"description": "ID of the user who will be marked as the owner of this deal. If omitted, the authorized user ID will be used.",
"type": "number"
},
{
"key": "person_id",
"description": "ID of the person this deal will be associated with",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the organization this deal will be associated with",
"type": "number"
},
{
"key": "stage_id",
"description": "ID of the stage this deal will be placed in a pipeline (note that you can't supply the ID of the pipeline as this will be assigned automatically based on stage_id). If omitted, the deal will be placed in the first stage of the default pipeline.",
"type": "number"
},
{
"key": "status",
"description": "open = Open, won = Won, lost = Lost, deleted = Deleted. If omitted, status will be set to open.",
"type": "enumerated",
"values": [
"",
"open",
"won",
"lost",
"deleted"
]
},
{
"key": "probability",
"description": "Deal success probability percentage. Used/shown only when deal_probability for the pipeline of the deal is enabled.",
"type": "number"
},
{
"key": "lost_reason",
"description": "Optional message about why the deal was lost (to be used when status=lost)",
"type": "string"
},
{
"key": "add_time",
"description": "Optional creation date & time of the deal in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS",
"type": "string"
},
{
"key": "visible_to",
"description": "Visibility of the deal. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.\n\n1\nOwner & followers (private)\n3\nEntire company (shared)",
"type": "enumerated",
"values": [
"",
"1",
"3"
]
}
]
}
],
[
{
"method": "POST",
"url": "/deals/{id}/duplicate",
"summary": "Duplicate a deal",
"parameters": [
{
"key": "id",
"description": "ID of the deal that will be duplicated",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/deals/{id}/followers",
"summary": "Adds a follower to a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "user_id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/deals/{id}/participants",
"summary": "Adds a participant to a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "person_id",
"description": "ID of the person",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/deals/{id}/products",
"summary": "Adds a product to the deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "product_id",
"description": "ID of the product that will be attached",
"type": "number"
},
{
"key": "item_price",
"description": "Price at which this product will be added to the deal",
"type": "number"
},
{
"key": "quantity",
"description": "Quantity – e.g. how many items of this product will be added to the deal",
"type": "number"
},
{
"key": "discount_percentage",
"description": "Discount %. If omitted, will be set to 0",
"type": "number"
},
{
"key": "duration",
"description": "Duration of the product (when product durations are not enabled for the company or if omitted, defaults to 1)",
"type": "number"
},
{
"key": "product_variation_id",
"description": "ID of the product variation to use. When omitted, no variation will be used.",
"type": "number"
},
{
"key": "comments",
"description": "Any textual comment associated with this product-deal attachment. Visible and editable in the application UI.",
"type": "string"
},
{
"key": "enabled_flag",
"description": "Whether the product is enabled on the deal or not. This makes it possible to add products to a deal with specific price and discount criteria - but keep them disabled, which refrains them from being included in deal price calculation. When omitted, the product will be marked as enabled by default.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "PUT",
"url": "/deals/{id}",
"summary": "Updates the properties of a deal. For more information on how to update a deal, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "title",
"description": "Deal title",
"type": "string"
},
{
"key": "value",
"description": "Value of the deal",
"type": "string"
},
{
"key": "currency",
"description": "Currency of the deal. Accepts a 3-character currency code",
"type": "string"
},
{
"key": "user_id",
"description": "ID of the user who will be marked as the owner of this deal",
"type": "number"
},
{
"key": "person_id",
"description": "ID of the person this deal will be associated with",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the organization this deal will be associated with",
"type": "number"
},
{
"key": "stage_id",
"description": "ID of the stage this deal will be placed in a pipeline (note that you can't supply the ID of the pipeline as this will be assigned automatically based on stage_id)",
"type": "number"
},
{
"key": "status",
"description": "open = Open, won = Won, lost = Lost, deleted = Deleted",
"type": "enumerated string"
},
{
"key": "probability",
"description": "Deal success probability percentage. Used/shown only when deal_probability for the pipeline of the deal is enabled.",
"type": "number"
},
{
"key": "lost_reason",
"description": "Optional message about why the deal was lost (to be used when status=lost)",
"type": "string"
},
{
"key": "visible_to",
"description": "Visibility of the deal. If omitted, visibility will not be changed.\n\n1\nOwner & followers (private)\n3\nEntire company (shared)",
"type": "enumerated",
"values": [
"",
"1",
"3"
]
}
]
}
],
[
{
"method": "PUT",
"url": "/deals/{id}/merge",
"summary": "Merges a deal with another deal. For more information on how to merge two deals, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the deal that will be merged",
"type": "number"
},
{
"key": "merge_with_id",
"description": "ID of the deal that the deal will be merged with",
"type": "number"
}
]
}
],
[
{
"method": "PUT",
"url": "/deals/{id}/products/{deal_product_id}",
"summary": "Updates product attachment details.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "deal_product_id",
"description": "ID of the deal-product (the ID of the product attached to the deal)",
"type": "number"
},
{
"key": "item_price",
"description": "Price at which this product will be added to the deal",
"type": "number"
},
{
"key": "quantity",
"description": "Quantity – e.g. how many items of this product will be added to the deal",
"type": "number"
},
{
"key": "discount_percentage",
"description": "Discount %",
"type": "number"
},
{
"key": "duration",
"description": "Duration of the product",
"type": "number"
},
{
"key": "product_variation_id",
"description": "ID of the product variation to use.",
"type": "number"
},
{
"key": "comments",
"description": "Any textual comment associated with this product-deal attachment. Visible and editable in the application UI.",
"type": "string"
},
{
"key": "enabled_flag",
"description": "Whether the product is enabled on the deal or not. This makes it possible to add products to a deal with specific price and discount criteria - but keep them disabled, which refrains them from being included in deal price calculation.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "DELETE",
"url": "/deals",
"summary": "Marks multiple deals as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated IDs that will be deleted",
"type": "array"
}
]
}
],
[
{
"method": "DELETE",
"url": "/deals/{id}",
"summary": "Marks a deal as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/deals/{id}/followers/{follower_id}",
"summary": "Deletes a follower from a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "follower_id",
"description": "ID of the follower",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/deals/{id}/participants/{deal_participant_id}",
"summary": "Deletes a participant from a deal.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "deal_participant_id",
"description": "ID of the deal participant",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/deals/{id}/products/{product_attachment_id}",
"summary": "Deletes a product attachment from a deal, using the product_attachment_id.",
"parameters": [
{
"key": "id",
"description": "ID of the deal",
"type": "number"
},
{
"key": "product_attachment_id",
"description": "Product attachment ID. This is returned as product_attachment_id after attaching a product to a deal or as id when listing the products attached to a deal.",
"type": "number"
}
]
}
]
]
},
{
"heading": "DealFields",
"description": "DealFields represent the near-complete schema for a Deal in the context of the company of the authorized user. Each company can have a different schema for their Deals, with various custom fields. In the context of using DealFiels as a schema for defining the data fields of a Deal, it must be kept in mind that some types of custom fields can have additional data fields which are not separate DealFields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of DealFields. For example, if there is a monetary field with the key 'ffk9s9' stored on the account, 'ffk9s9' would hold the numeric value of the field, and 'ffk9s9_currency' would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one Deal and list its keys.",
"endpoint": [
[
{
"method": "GET",
"url": "/dealFields",
"summary": "Returns data about all fields deals can have",
"parameters": [
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/dealFields/{id}",
"summary": "Returns data about a specific deal field.",
"parameters": [
{
"key": "id",
"description": "ID of the field to fetch.",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/dealFields",
"summary": "Adds a new deal field. For more information on adding a new custom field, see this tutorial.",
"parameters": [
{
"key": "name",
"description": "Name of the field",
"type": "string"
},
{
"key": "field_type",
"description": "Type of the field.\n\nvarchar\nText (up to 255 characters)\nvarchar_auto\nAutocomplete text (up to 255 characters)\ntext\nLong text (up to 65k characters)\ndouble\nNumeric value\nmonetary\nMonetary field (has a numeric value and a currency value)\ndate\nDate (format YYYY-MM-DD)\nset\nOptions field with a possibility of having multiple chosen options\nenum\nOptions field with a single possible chosen option\nuser\nUser field (contains a user ID of another Pipedrive user)\norg\nOrganization field (contains an organization ID which is stored on the same account)\npeople\nPerson field (contains a person ID which is stored on the same account)\nphone\nPhone field (up to 255 numbers and/or characters)\ntime\nTime field (format HH:MM:SS)\ntimerange\nTime-range field (has a start time and end time value, both HH:MM:SS)\ndaterange\nDate-range field (has a start date and end date value, both YYYY-MM-DD)",
"type": "enumerated",
"values": [
"varchar",
"varchar_auto",
"text",
"double",
"monetary",
"date",
"set",
"enum",
"user",
"org",
"people",
"phone",
"time",
"timerange",
"daterange"
]
},
{
"key": "options",
"description": "When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array, for example: [\"red\",\"blue\",\"lilac\"]",
"type": "json string"
}
]
}
],
[
{
"method": "PUT",
"url": "/dealFields/{id}",
"summary": "Updates a deal field. See an example of updating custom fields’ values in this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the field to update.",
"type": "number"
},
{
"key": "name",
"description": "Name of the field",
"type": "string"
},
{
"key": "options",
"description": "When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{\"id\":123,\"label\":\"Existing Item\"},{\"label\":\"New Item\"}]",
"type": "json string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/dealFields",
"summary": "Marks multiple fields as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated field IDs to delete",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/dealFields/{id}",
"summary": "Marks a field as deleted. For more information on how to delete a custom field, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the field to delete.",
"type": "number"
}
]
}
]
]
},
{
"heading": "Files",
"description": "Files are documents of any kind (images, spreadsheets, text files, etc.) that are uploaded to Pipedrive, and usually associated with a particular Deal, Person, Organization, Product, Note or Activity. Remote files can only be associated with a particular Deal, Person or Organization. Note that the API currently does not support downloading files although it lets you retrieve a file’s meta-info along with a URL which can be used to download the file by using a standard HTTP GET request.",
"endpoint": [
[
{
"method": "GET",
"url": "/files",
"summary": "Returns data about all files.",
"parameters": [
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "include_deleted_files",
"description": "When enabled, the list of files will also include deleted files. Please note that trying to download these files will not work.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, product_id, add_time, update_time, file_name, file_type, file_size, comment.",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/files/{id}",
"summary": "Returns data about a specific file.",
"parameters": [
{
"key": "id",
"description": "ID of the file to fetch",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/files/{id}/download",
"summary": "Initializes a file download.",
"parameters": [
{
"key": "id",
"description": "ID of the file to download",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/files",
"summary": "Lets you upload a file and associate it with Deal, Person, Organization, Activity or Product. For more information on how to add a file, see this tutorial.",
"parameters": [
{
"key": "file",
"description": "A single file, supplied in the multipart/form-data encoding and contained within the given boundaries.",
"type": "file"
},
{
"key": "deal_id",
"description": "ID of the deal to associate file(s) with",
"type": "number"
},
{
"key": "person_id",
"description": "ID of the person to associate file(s) with",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the organization to associate file(s) with",
"type": "number"
},
{
"key": "product_id",
"description": "ID of the product to associate file(s) with",
"type": "number"
},
{
"key": "activity_id",
"description": "ID of the activity to associate file(s) with",
"type": "number"
},
{
"key": "note_id",
"description": "ID of the note to associate file(s) with",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/files/remote",
"summary": "Creates a new empty file in the remote location (googledrive) that will be linked to the item you supply. For more information on how to add a remote file, see this tutorial.",
"parameters": [
{
"key": "file_type",
"description": "The file type",
"type": "enumerated",
"values": [
"gdoc",
"gslides",
"gsheet",
"gform",
"gdraw"
]
},
{
"key": "title",
"description": "The title of the file",
"type": "string"
},
{
"key": "item_type",
"description": "The item type",
"type": "enumerated",
"values": [
"deal",
"organization",
"person"
]
},
{
"key": "item_id",
"description": "ID of the item to associate the file with",
"type": "number"
},
{
"key": "remote_location",
"description": "The location type to send the file to. Only googledrive is supported at the moment.",
"type": "enumerated",
"values": [
"googledrive"
]
}
]
}
],
[
{
"method": "POST",
"url": "/files/remoteLink",
"summary": "Links an existing remote file (googledrive) to the item you supply. For more information on how to link a remote file, see this tutorial.",
"parameters": [
{
"key": "item_type",
"description": "The item type",
"type": "enumerated",
"values": [
"deal",
"organization",
"person"
]
},
{
"key": "item_id",
"description": "ID of the item to associate the file with",
"type": "number"
},
{
"key": "remote_id",
"description": "The remote item id",
"type": "string"
},
{
"key": "remote_location",
"description": "The location type to send the file to. Only googledrive is supported at the moment.",
"type": "enumerated",
"values": [
"googledrive"
]
}
]
}
],
[
{
"method": "PUT",
"url": "/files/{id}",
"summary": "Updates the properties of a file.",
"parameters": [
{
"key": "id",
"description": "ID of the file",
"type": "number"
},
{
"key": "name",
"description": "Visible name of the file",
"type": "string"
},
{
"key": "description",
"description": "Description of the file",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/files/{id}",
"summary": "Marks a file as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the file to delete",
"type": "number"
}
]
}
]
]
},
{
"heading": "Filters",
"description": "Each filter is essentially a set of data validation conditions. A filter of the same kind can be applied when fetching list of Deals, Persons, Organizations, Products or Deals in the context of a Pipeline. When applied, only items matching the conditions of the filter are returned. Detailed definitions of filter conditions and additional functionality is not yet available.",
"endpoint": [
[
{
"method": "GET",
"url": "/filters",
"summary": "Returns data about all filters",
"parameters": [
{
"key": "type",
"description": "Type of filters to fetch.",
"type": "enumerated",
"values": [
"",
"deals",
"org",
"people",
"products",
"activity"
]
}
]
}
],
[
{
"method": "GET",
"url": "/filters/helpers",
"summary": "Returns all supported filter helpers. It helps to know what conditions and helpers are available when you want to add or update filters. For more information on how filter’s helpers can be used, see this tutorial.",
"parameters": []
}
],
[
{
"method": "GET",
"url": "/filters/{id}",
"summary": "Returns data about a specific filter. Note that this also returns the condition lines of the filter.",
"parameters": [
{
"key": "id",
"description": "ID of the filter to fetch.",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/filters",
"summary": "Adds a new filter, returns the ID upon success. Note that in the conditions json object only one first-level condition group is supported, and it must be glued with 'AND', and only two second level condition groups are supported of which one must be glued with 'AND' and the second with 'OR'. Other combinations do not work (yet) but the syntax supports introducing them in future. For more information on how to add a new filter, see this tutorial.",
"parameters": [
{
"key": "name",
"description": "Filter name",
"type": "string"
},
{
"key": "conditions",
"description": "Filter conditions as a JSON object. It requires a minimum structure as follows: {\"glue\":\"and\",\"conditions\":[{\"glue\":\"and\",\"conditions\": [CONDITION_OBJECTS]},{\"glue\":\"or\",\"conditions\":[CONDITION_OBJECTS]}]}. Replace CONDITION_OBJECTS with JSON objects of the following structure: {\"object\":\"\",\"field_id\":\"\", \"operator\":\"\",\"value\":\"\", \"extra_value\":\"\"} or leave the array empty. Depending on the object type you should use another API endpoint to get field_id. There are five types of objects you can choose from: \"person\", \"deal\", \"organization\", \"product\", \"activity\" and you can use these types of operators depending on what type of a field you have: \"IS NOT NULL\", \"IS NULL\", \"<=\", \">=\", \"<\", \">\", \"!=\", \"=\", \"LIKE '%$%'\", \"NOT LIKE '%$%'\", \"LIKE '$%'\", \"NOT LIKE '$%'\", \"LIKE '%$'\", \"NOT LIKE '%$'\". To get a better understanding of how filters work try creating them directly from the Pipedrive application.",
"type": "json string"
},
{
"key": "type",
"description": "Type of filter to create.",
"type": "enumerated",
"values": [
"deals",
"org",
"people",
"products",
"activity"
]
}
]
}
],
[
{
"method": "PUT",
"url": "/filters/{id}",
"summary": "Updates existing filter.",
"parameters": [
{
"key": "id",
"description": "ID of the filter to update.",
"type": "number"
},
{
"key": "name",
"description": "Filter name",
"type": "string"
},
{
"key": "conditions",
"description": "Filter conditions as a JSON object. It requires a minimum structure as follows: {\"glue\":\"and\",\"conditions\":[{\"glue\":\"and\",\"conditions\": [CONDITION_OBJECTS]},{\"glue\":\"or\",\"conditions\":[CONDITION_OBJECTS]}]}. Replace CONDITION_OBJECTS with JSON objects of the following structure: {\"object\":\"\",\"field_id\":\"\", \"operator\":\"\",\"value\":\"\", \"extra_value\":\"\"} or leave the array empty. Depending on the object type you should use another API endpoint to get field_id. There are five types of objects you can choose from: \"person\", \"deal\", \"organization\", \"product\", \"activity\" and you can use these types of operators depending on what type of a field you have: \"IS NOT NULL\", \"IS NULL\", \"<=\", \">=\", \"<\", \">\", \"!=\", \"=\", \"LIKE '%$%'\", \"NOT LIKE '%$%'\", \"LIKE '$%'\", \"NOT LIKE '$%'\", \"LIKE '%$'\", \"NOT LIKE '%$'\". To get a better understanding of how filters work try creating them directly from the Pipedrive application.",
"type": "json string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/filters",
"summary": "Marks multiple filters as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated filter IDs to delete",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/filters/{id}",
"summary": "Marks a filter as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the filter to delete.",
"type": "number"
}
]
}
]
]
},
{
"heading": "GlobalMessages",
"description": "Get or dismiss global messages",
"endpoint": [
[
{
"method": "GET",
"url": "/globalMessages",
"summary": "Returns data about global messages to display for the authorized user.",
"parameters": [
{
"key": "limit",
"description": "Number of messages to get from 1 to 100. 1 message is returned by default.",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/globalMessages/{id}",
"summary": "Removes global message from being shown, if message is dismissible",
"parameters": [
{
"key": "id",
"description": "ID of global message to be dismissed.",
"type": "number"
}
]
}
]
]
},
{
"heading": "MailMessages",
"description": "MailMessages represent mail messages that are being synced with Piperive using the 2-way sync or the Smart Email BCC feature. Messages are grouped in threads.",
"endpoint": [
[
{
"method": "GET",
"url": "/mailbox/mailMessages/{id}",
"summary": "Returns data about specific mail message.",
"parameters": [
{
"key": "id",
"description": "ID of the mail message to fetch.",
"type": "number"
},
{
"key": "include_body",
"description": "Whether to include full message body or not. 0 = Don't include, 1 = Include",
"type": "enumerated",
"values": [
"0",
"1"
]
}
]
}
]
]
},
{
"heading": "MailThreads",
"description": "MailThreads represent mail threads which contain individual mail messages.",
"endpoint": [
[
{
"method": "GET",
"url": "/mailbox/mailThreads",
"summary": "Returns mail threads in specified folder ordered by most recent message within.",
"parameters": [
{
"key": "folder",
"description": "Type of folder to fetch.",
"type": "enumerated",
"values": [
"inbox",
"drafts",
"sent",
"archive"
]
},
{
"key": "start",
"description": "Index of the first item. If not set, then equals 0.",
"type": "number"
},
{
"key": "limit",
"description": "Amount of threads to fetch. If not set, then equals 50.",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/mailbox/mailThreads/{id}",
"summary": "Returns specific mail thread.",
"parameters": [
{
"key": "id",
"description": "ID of the mail thread to fetch.",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/mailbox/mailThreads/{id}/mailMessages",
"summary": "Get mail messages inside specified mail thread.",
"parameters": [
{
"key": "id",
"description": "ID of the mail thread.",
"type": "number"
}
]
}
],
[
{
"method": "PUT",
"url": "/mailbox/mailThreads/{id}",
"summary": "Updates the properties of a mail thread.",
"parameters": [
{
"key": "id",
"description": "ID of the mail thread",
"type": "number"
},
{
"key": "deal_id",
"description": "ID of the deal this thread is associated with",
"type": "number"
},
{
"key": "shared_flag",
"description": "Whether this thread is shared with other users in your company",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "read_flag",
"description": "Whether this thread read or unread",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "archived_flag",
"description": "Whether this thread is archived or not. You can only archive threads that belong to Inbox folder. Archived threads will disappear from Inbox.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "DELETE",
"url": "/mailbox/mailThreads/{id}",
"summary": "Marks mail thread as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the mail thread to delete.",
"type": "number"
}
]
}
]
]
},
{
"heading": "Notes",
"description": "Notes are pieces of textual (HTML-formatted) information that can be attached to Deals, Persons and Organizations. Notes are usually displayed in the UI in chronological order – newest first – and in context with other updates regarding the item they are attached to. The maximum note size is approximately 3,000,000 characters (or 3MB per note).",
"endpoint": [
[
{
"method": "GET",
"url": "/notes",
"summary": "Returns all notes.",
"parameters": [
{
"key": "user_id",
"description": "ID of the user whose notes to fetch. If omitted, notes by all users will be returned.",
"type": "number"
},
{
"key": "deal_id",
"description": "ID of the deal which notes to fetch. If omitted, notes about all deals with be returned.",
"type": "number"
},
{
"key": "person_id",
"description": "ID of the person whose notes to fetch. If omitted, notes about all persons with be returned.",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the organization which notes to fetch. If omitted, notes about all organizations with be returned.",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, content, add_time, update_time.",
"type": "string"
},
{
"key": "start_date",
"description": "Date in format of YYYY-MM-DD from which notes to fetch from.",
"type": "date"
},
{
"key": "end_date",
"description": "Date in format of YYYY-MM-DD until which notes to fetch to.",
"type": "date"
},
{
"key": "pinned_to_deal_flag",
"description": "If set, then results are filtered by note to deal pinning state.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "pinned_to_organization_flag",
"description": "If set, then results are filtered by note to organization pinning state.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "pinned_to_person_flag",
"description": "If set, then results are filtered by note to person pinning state.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "GET",
"url": "/notes/{id}",
"summary": "Returns details about a specific note.",
"parameters": [
{
"key": "id",
"description": "ID of the note",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/notes",
"summary": "Adds a new note.",
"parameters": [
{
"key": "content",
"description": "Content of the note in HTML format. Subject to sanitization on the back-end.",
"type": "string"
},
{
"key": "deal_id",
"description": "ID of the deal the note will be attached to.",
"type": "number"
},
{
"key": "person_id",
"description": "ID of the person this note will be attached to.",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the organization this note will be attached to.",
"type": "number"
},
{
"key": "add_time",
"description": "Optional creation date & time of the Note in UTC. Can be set in the past or in the future. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS",
"type": "string"
},
{
"key": "pinned_to_deal_flag",
"description": "If set, then results are filtered by note to deal pinning state (deal_id is also required).",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "pinned_to_organization_flag",
"description": "If set, then results are filtered by note to organization pinning state (org_id is also required).",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "pinned_to_person_flag",
"description": "If set, then results are filtered by note to person pinning state (person_id is also required).",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "PUT",
"url": "/notes/{id}",
"summary": "Updates a note.",
"parameters": [
{
"key": "id",
"description": "ID of the note",
"type": "number"
},
{
"key": "content",
"description": "Content of the note in HTML format. Subject to sanitization on the back-end.",
"type": "string"
},
{
"key": "deal_id",
"description": "ID of the deal the note will be attached to.",
"type": "number"
},
{
"key": "person_id",
"description": "ID of the person this note will be attached to.",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the organization this note will be attached to.",
"type": "number"
},
{
"key": "add_time",
"description": "Optional creation date & time of the Note in UTC. Can be set in the past or in the future. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS",
"type": "string"
},
{
"key": "pinned_to_deal_flag",
"description": "If set, then results are filtered by note to deal pinning state.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "pinned_to_organization_flag",
"description": "If set, then results are filtered by note to organization pinning state.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "pinned_to_person_flag",
"description": "If set, then results are filtered by note to person pinning state.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "DELETE",
"url": "/notes/{id}",
"summary": "Deletes a specific note.",
"parameters": [
{
"key": "id",
"description": "ID of the note",
"type": "number"
}
]
}
]
]
},
{
"heading": "NoteFields",
"description": "NoteFields represent different fields that Note has.",
"endpoint": [
[
{
"method": "GET",
"url": "/noteFields",
"summary": "Return list of all fields for note",
"parameters": []
}
]
]
},
{
"heading": "OrganizationFields",
"description": "OrganizationFields represent the near-complete schema for an Organization in the context of the company of the authorized user. Each company can have a different schema for their Organizations, with various custom fields. In the context of using OrganizationFiels as a schema for defining the data fields of an Organization, it must be kept in mind that some types of custom fields can have additional data fields which are not separate OrganizationFields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of OrganizationFields. For example, if there is a monetary field with the key 'ffk9s9' stored on the account, 'ffk9s9' would hold the numeric value of the field, and 'ffk9s9_currency' would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one Organization and list its keys.",
"endpoint": [
[
{
"method": "GET",
"url": "/organizationFields",
"summary": "Returns data about all organization fields",
"parameters": []
}
],
[
{
"method": "GET",
"url": "/organizationFields/{id}",
"summary": "Returns data about a specific organization field.",
"parameters": [
{
"key": "id",
"description": "ID of the field to fetch.",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/organizationFields",
"summary": "Adds a new organization field. For more information on adding a new custom field, see this tutorial.",
"parameters": [
{
"key": "name",
"description": "Name of the field",
"type": "string"
},
{
"key": "field_type",
"description": "Type of the field.\n\nvarchar\nText (up to 255 characters)\nvarchar_auto\nAutocomplete text (up to 255 characters)\ntext\nLong text (up to 65k characters)\ndouble\nNumeric value\nmonetary\nMonetary field (has a numeric value and a currency value)\ndate\nDate (format YYYY-MM-DD)\nset\nOptions field with a possibility of having multiple chosen options\nenum\nOptions field with a single possible chosen option\nuser\nUser field (contains a user ID of another Pipedrive user)\norg\nOrganization field (contains an organization ID which is stored on the same account)\npeople\nPerson field (contains a person ID which is stored on the same account)\nphone\nPhone field (up to 255 numbers and/or characters)\ntime\nTime field (format HH:MM:SS)\ntimerange\nTime-range field (has a start time and end time value, both HH:MM:SS)\ndaterange\nDate-range field (has a start date and end date value, both YYYY-MM-DD)",
"type": "enumerated",
"values": [
"varchar",
"varchar_auto",
"text",
"double",
"monetary",
"date",
"set",
"enum",
"user",
"org",
"people",
"phone",
"time",
"timerange",
"daterange"
]
},
{
"key": "options",
"description": "When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array, for example: [\"red\",\"blue\",\"lilac\"]",
"type": "json string"
}
]
}
],
[
{
"method": "PUT",
"url": "/organizationFields/{id}",
"summary": "Updates an organization field. See an example of updating custom fields’ values in this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the field to update.",
"type": "number"
},
{
"key": "name",
"description": "Name of the field",
"type": "string"
},
{
"key": "options",
"description": "When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{\"id\":123,\"label\":\"Existing Item\"},{\"label\":\"New Item\"}]",
"type": "json string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/organizationFields",
"summary": "Marks multiple fields as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated field IDs to delete",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/organizationFields/{id}",
"summary": "Marks a field as deleted. For more information on how to delete a custom field, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the field to delete.",
"type": "number"
}
]
}
]
]
},
{
"heading": "Organizations",
"description": "Organizations are companies and other kinds of organizations you are making Deals with. Persons can be associated with organizations so that each organization can contain one or more Persons.",
"endpoint": [
[
{
"method": "GET",
"url": "/organizations",
"summary": "Returns all organizations",
"parameters": [
{
"key": "user_id",
"description": "If supplied, only organizations owned by the given user will be returned.",
"type": "number"
},
{
"key": "filter_id",
"description": "ID of the filter to use",
"type": "number"
},
{
"key": "first_char",
"description": "If supplied, only organizations whose name starts with the specified letter will be returned (case insensitive).",
"type": "string"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/find",
"summary": "Searches all organizations by their name.",
"parameters": [
{
"key": "term",
"description": "Search term to look for",
"type": "string"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/{id}",
"summary": "Returns details of an organization. Note that this also returns some additional fields which are not present when asking for all organizations. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the 'key' value of organizationFields.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/{id}/activities",
"summary": "Lists activities associated with an organization.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "done",
"description": "Whether to fetch done (1) or undone (0) activities. If omitted from request, both undone and done activities are fetched.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "exclude",
"description": "A comma-separated string of activity IDs to exclude from result",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/{id}/deals",
"summary": "Lists deals associated with an organization.",
"parameters": [
{
"key": "id",
"description": "ID of an organization",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "status",
"description": "Only fetch deals with specific status. If omitted, all not deleted deals are fetched.",
"type": "enumerated",
"values": [
"open",
"won",
"lost",
"deleted",
"all_not_deleted"
]
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).",
"type": "string"
},
{
"key": "only_primary_association",
"description": "If set, only deals that are directly associated to the organization are fetched. If not set (default), all deals are fetched that are either directly or indirectly related to the organization. Indirect relations include relations through custom, organization-type fields and through persons of the given organization.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/{id}/files",
"summary": "Lists files associated with an organization.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "include_deleted_files",
"description": "When enabled, the list of files will also include deleted files. Please note that trying to download these files will not work.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, product_id, add_time, update_time, file_name, file_type, file_size, comment.",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/{id}/flow",
"summary": "Lists updates about an organization.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/{id}/followers",
"summary": "Lists the followers of an organization.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/{id}/mailMessages",
"summary": "Lists mail messages associated with an organization.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/{id}/permittedUsers",
"summary": "List users permitted to access an organization",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
},
{
"key": "access_level",
"description": "If set, filter results by allowed access level. 1 = Read, 2 = Write, 3 = Read+Write",
"type": "enumerated",
"values": [
"",
"1",
"2",
"3"
]
}
]
}
],
[
{
"method": "GET",
"url": "/organizations/{id}/persons",
"summary": "Lists persons associated with an organization.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/organizations",
"summary": "Adds a new organization. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys. To determine which custom fields exists, fetch the organizationFields and look for 'key' values. For more information on how to add an organization, see this tutorial.",
"parameters": [
{
"key": "name",
"description": "Organization name",
"type": "string"
},
{
"key": "owner_id",
"description": "ID of the user who will be marked as the owner of this organization. When omitted, the authorized user ID will be used.",
"type": "number"
},
{
"key": "visible_to",
"description": "Visibility of the organization. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.\n\n1\nOwner & followers (private)\n3\nEntire company (shared)",
"type": "enumerated",
"values": [
"",
"1",
"3"
]
},
{
"key": "add_time",
"description": "Optional creation date & time of the organization in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS",
"type": "string"
}
]
}
],
[
{
"method": "POST",
"url": "/organizations/{id}/followers",
"summary": "Adds a follower to an organization.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
},
{
"key": "user_id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "PUT",
"url": "/organizations/{id}",
"summary": "Updates the properties of an organization.",
"parameters": [
{
"key": "id",
"description": "Organization ID",
"type": "number"
},
{
"key": "name",
"description": "Organization name",
"type": "string"
},
{
"key": "owner_id",
"description": "ID of the user who will be marked as the owner of this organization. When omitted, the authorized user ID will be used.",
"type": "number"
},
{
"key": "visible_to",
"description": "Visibility of the organization. If omitted, visibility will not be changed.\n\n1\nOwner & followers (private)\n3\nEntire company (shared)",
"type": "enumerated",
"values": [
"",
"1",
"3"
]
}
]
}
],
[
{
"method": "PUT",
"url": "/organizations/{id}/merge",
"summary": "Merges an organization with another organization. For more information on how to merge two organizations, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the organization that will be merged",
"type": "number"
},
{
"key": "merge_with_id",
"description": "ID of the organization that the organization will be merged with",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/organizations",
"summary": "Marks multiple organizations as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated IDs that will be deleted",
"type": "array"
}
]
}
],
[
{
"method": "DELETE",
"url": "/organizations/{id}",
"summary": "Marks an organization as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/organizations/{id}/followers/{follower_id}",
"summary": "Deletes a follower from an organization. You can retrieve the follower_id from the List followers of an organization endpoint.",
"parameters": [
{
"key": "id",
"description": "ID of the organization",
"type": "number"
},
{
"key": "follower_id",
"description": "ID of the follower",
"type": "number"
}
]
}
]
]
},
{
"heading": "OrganizationRelationships",
"description": "Gets all of the relationships for a supplied organization id.",
"endpoint": [
[
{
"method": "GET",
"url": "/organizationRelationships",
"summary": "Gets all of the relationships for a supplied organization id.",
"parameters": [
{
"key": "org_id",
"description": "ID of the organization to get relationships for",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/organizationRelationships/{id}",
"summary": "Finds and returns an organization relationship from its ID.",
"parameters": [
{
"key": "id",
"description": "ID of the organization relationship",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the base organization for the returned calculated values",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/organizationRelationships",
"summary": "Creates and returns an organization relationship.",
"parameters": [
{
"key": "org_id",
"description": "ID of the base organization for the returned calculated values",
"type": "number"
},
{
"key": "type",
"description": "The type of organization relationship.",
"type": "enumerated",
"values": [
"parent",
"related"
]
},
{
"key": "rel_owner_org_id",
"description": "The owner of this relationship. If type is 'parent', then the owner is the parent and the linked organization is the daughter.",
"type": "number"
},
{
"key": "rel_linked_org_id",
"description": "The linked organization in this relationship. If type is 'parent', then the linked organization is the daughter.",
"type": "number"
}
]
}
],
[
{
"method": "PUT",
"url": "/organizationRelationships/{id}",
"summary": "Updates and returns an organization relationship.",
"parameters": [
{
"key": "id",
"description": "ID of the organization relationship",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the base organization for the returned calculated values",
"type": "number"
},
{
"key": "type",
"description": "The type of organization relationship.",
"type": "enumerated",
"values": [
"",
"parent",
"related"
]
},
{
"key": "rel_owner_org_id",
"description": "The owner of this relationship. If type is 'parent', then the owner is the parent and the linked organization is the daughter.",
"type": "number"
},
{
"key": "rel_linked_org_id",
"description": "The linked organization in this relationship. If type is 'parent', then the linked organization is the daughter.",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/organizationRelationships/{id}",
"summary": "Deletes an organization relationship and returns the deleted id.",
"parameters": [
{
"key": "id",
"description": "ID of the organization relationship",
"type": "number"
}
]
}
]
]
},
{
"heading": "PermissionSets",
"description": "List assignments for a permission set",
"endpoint": [
[
{
"method": "GET",
"url": "/permissionSets",
"summary": "",
"parameters": []
}
],
[
{
"method": "GET",
"url": "/permissionSets/{id}",
"summary": "",
"parameters": [
{
"key": "id",
"description": "ID of the permission set",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/permissionSets/{id}/assignments",
"summary": "List assignments for a permission set",
"parameters": [
{
"key": "id",
"description": "ID of the permission set",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/permissionSets/{id}/assignments",
"summary": "Add assignment for a permission set",
"parameters": [
{
"key": "id",
"description": "ID of the permission set",
"type": "number"
},
{
"key": "user_id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "PUT",
"url": "/permissionSets/{id}",
"summary": "",
"parameters": [
{
"key": "id",
"description": "ID of the permission set",
"type": "number"
},
{
"key": "contents",
"description": "Permissions that this set contains as JSON or ordinary comma separated string. Possible permission names are: can_change_visibility_of_items, can_see_company_wide_statistics, can_delete_deals, can_see_deals_list_summary, can_export_data_from_lists, can_see_other_users_statistics",
"type": "json string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/permissionSets/{id}/assignments",
"summary": "Delete assignment from a permission set",
"parameters": [
{
"key": "id",
"description": "ID of the permission set",
"type": "number"
},
{
"key": "user_id",
"description": "ID of the user",
"type": "number"
}
]
}
]
]
},
{
"heading": "Persons",
"description": "Persons are your contacts, the customers you are doing Deals with. Each Person can belong to an Organization. Persons should not be confused with Users.",
"endpoint": [
[
{
"method": "GET",
"url": "/persons",
"summary": "Returns all persons",
"parameters": [
{
"key": "user_id",
"description": "If supplied, only persons owned by the given user will be returned.",
"type": "number"
},
{
"key": "filter_id",
"description": "ID of the filter to use",
"type": "number"
},
{
"key": "first_char",
"description": "If supplied, only persons whose name starts with the specified letter will be returned (case insensitive).",
"type": "string"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/persons/find",
"summary": "Searches all persons by their name.",
"parameters": [
{
"key": "term",
"description": "Search term to look for",
"type": "string"
},
{
"key": "org_id",
"description": "ID of the organization person is associated with.",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "search_by_email",
"description": "When enabled, term will only be matched against email addresses of people. Default: false",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "GET",
"url": "/persons/{id}",
"summary": "Returns details of a person. Note that this also returns some additional fields which are not present when asking for all persons. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the 'key' value of personFields.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/persons/{id}/activities",
"summary": "Lists activities associated with a person.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "done",
"description": "Whether to fetch done (1) or undone (0) activities. If omitted from request, both undone and done activities are fetched.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "exclude",
"description": "A comma-separated string of activity IDs to exclude from result",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/persons/{id}/deals",
"summary": "Lists deals associated with a person.",
"parameters": [
{
"key": "id",
"description": "ID of a person",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "status",
"description": "Only fetch deals with specific status. If omitted, all not deleted deals are fetched.",
"type": "enumerated",
"values": [
"open",
"won",
"lost",
"deleted",
"all_not_deleted"
]
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/persons/{id}/files",
"summary": "Lists files associated with a person.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "include_deleted_files",
"description": "When enabled, the list of files will also include deleted files. Please note that trying to download these files will not work.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, product_id, add_time, update_time, file_name, file_type, file_size, comment.",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/persons/{id}/flow",
"summary": "Lists updates about a person.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/persons/{id}/followers",
"summary": "Lists the followers of a person.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/persons/{id}/mailMessages",
"summary": "Lists mail messages associated with a person.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/persons/{id}/permittedUsers",
"summary": "List users permitted to access a person",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
},
{
"key": "access_level",
"description": "If set, filter results by allowed access level. 1 = Read, 2 = Write, 3 = Read+Write",
"type": "enumerated",
"values": [
"",
"1",
"2",
"3"
]
}
]
}
],
[
{
"method": "GET",
"url": "/persons/{id}/products",
"summary": "Lists products associated with a person.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/persons",
"summary": "Adds a new person. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys. To determine which custom fields exists, fetch the personFields and look for 'key' values.",
"parameters": [
{
"key": "name",
"description": "Person name",
"type": "string"
},
{
"key": "owner_id",
"description": "ID of the user who will be marked as the owner of this person. When omitted, the authorized user ID will be used.",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the organization this person will belong to.",
"type": "number"
},
{
"key": "email",
"description": "Email addresses (one or more) associated with the person, presented in the same manner as received by GET request of a person.",
"type": "array"
},
{
"key": "phone",
"description": "Phone numbers (one or more) associated with the person, presented in the same manner as received by GET request of a person.",
"type": "array"
},
{
"key": "visible_to",
"description": "Visibility of the person. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.\n\n1\nOwner & followers (private)\n3\nEntire company (shared)",
"type": "enumerated",
"values": [
"",
"1",
"3"
]
},
{
"key": "add_time",
"description": "Optional creation date & time of the person in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS",
"type": "string"
}
]
}
],
[
{
"method": "POST",
"url": "/persons/{id}/followers",
"summary": "Adds a follower to a person.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
},
{
"key": "user_id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/persons/{id}/picture",
"summary": "Add a picture to a person. If a picture is already set, the old picture will be replaced. Added image (or the cropping parameters supplied with the request) should have an equal width and height and should be at least 128 pixels. GIF, JPG and PNG are accepted. All added images will be resized to 128 and 512 pixel wide squares.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
},
{
"key": "file",
"description": "One image supplied in the multipart/form-data encoding.",
"type": "file"
},
{
"key": "crop_x",
"description": "X coordinate to where start cropping form (in pixels)",
"type": "number"
},
{
"key": "crop_y",
"description": "Y coordinate to where start cropping form (in pixels)",
"type": "number"
},
{
"key": "crop_width",
"description": "Width of cropping area (in pixels)",
"type": "number"
},
{
"key": "crop_height",
"description": "Height of cropping area (in pixels)",
"type": "number"
}
]
}
],
[
{
"method": "PUT",
"url": "/persons/{id}",
"summary": "Updates the properties of a person. For more information on how to update a person, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "Person ID",
"type": "number"
},
{
"key": "name",
"description": "Person name",
"type": "string"
},
{
"key": "owner_id",
"description": "ID of the user who will be marked as the owner of this person. When omitted, the authorized user ID will be used.",
"type": "number"
},
{
"key": "org_id",
"description": "ID of the organization this person will belong to.",
"type": "number"
},
{
"key": "email",
"description": "Email addresses (one or more) associated with the person, presented in the same manner as received by GET request of a person.",
"type": "array"
},
{
"key": "phone",
"description": "Phone numbers (one or more) associated with the person, presented in the same manner as received by GET request of a person.",
"type": "array"
},
{
"key": "visible_to",
"description": "Visibility of the person. If omitted, visibility will not be changed.\n\n1\nOwner & followers (private)\n3\nEntire company (shared)",
"type": "enumerated",
"values": [
"",
"1",
"3"
]
}
]
}
],
[
{
"method": "PUT",
"url": "/persons/{id}/merge",
"summary": "Merges a person with another person. For more information on how to merge two persons, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the person that will be merged",
"type": "number"
},
{
"key": "merge_with_id",
"description": "ID of the person that the person will be merged with",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/persons",
"summary": "Marks multiple persons as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated IDs that will be deleted",
"type": "array"
}
]
}
],
[
{
"method": "DELETE",
"url": "/persons/{id}",
"summary": "Marks a person as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/persons/{id}/followers/{follower_id}",
"summary": "Deletes a follower from a person.",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
},
{
"key": "follower_id",
"description": "ID of the follower",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/persons/{id}/picture",
"summary": "Delete person picture",
"parameters": [
{
"key": "id",
"description": "ID of the person",
"type": "number"
}
]
}
]
]
},
{
"heading": "PersonFields",
"description": "PersonFields represent the near-complete schema for a Person in the context of the company of the authorized user. Each company can have a different schema for their Persons, with various custom fields. In the context of using PersonFields as a schema for defining the data fields of a Person, it must be kept in mind that some types of custom fields can have additional data fields which are not separate PersonFields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of PersonFields. For example, if there is a monetary field with the key 'ffk9s9' stored on the account, 'ffk9s9' would hold the numeric value of the field, and 'ffk9s9_currency' would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one Person and list its keys.",
"endpoint": [
[
{
"method": "GET",
"url": "/personFields",
"summary": "Returns data about all person fields",
"parameters": []
}
],
[
{
"method": "GET",
"url": "/personFields/{id}",
"summary": "Returns data about a specific person field.",
"parameters": [
{
"key": "id",
"description": "ID of the field to fetch.",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/personFields",
"summary": "Adds a new person field. For more information on adding a new custom field, see this tutorial.",
"parameters": [
{
"key": "name",
"description": "Name of the field",
"type": "string"
},
{
"key": "field_type",
"description": "Type of the field.\n\nvarchar\nText (up to 255 characters)\nvarchar_auto\nAutocomplete text (up to 255 characters)\ntext\nLong text (up to 65k characters)\ndouble\nNumeric value\nmonetary\nMonetary field (has a numeric value and a currency value)\ndate\nDate (format YYYY-MM-DD)\nset\nOptions field with a possibility of having multiple chosen options\nenum\nOptions field with a single possible chosen option\nuser\nUser field (contains a user ID of another Pipedrive user)\norg\nOrganization field (contains an organization ID which is stored on the same account)\npeople\nPerson field (contains a person ID which is stored on the same account)\nphone\nPhone field (up to 255 numbers and/or characters)\ntime\nTime field (format HH:MM:SS)\ntimerange\nTime-range field (has a start time and end time value, both HH:MM:SS)\ndaterange\nDate-range field (has a start date and end date value, both YYYY-MM-DD)",
"type": "enumerated",
"values": [
"varchar",
"varchar_auto",
"text",
"double",
"monetary",
"date",
"set",
"enum",
"user",
"org",
"people",
"phone",
"time",
"timerange",
"daterange"
]
},
{
"key": "options",
"description": "When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array, for example: [\"red\",\"blue\",\"lilac\"]",
"type": "json string"
}
]
}
],
[
{
"method": "PUT",
"url": "/personFields/{id}",
"summary": "Updates a person field. See an example of updating custom fields’ values in this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the field to update.",
"type": "number"
},
{
"key": "name",
"description": "Name of the field",
"type": "string"
},
{
"key": "options",
"description": "When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{\"id\":123,\"label\":\"Existing Item\"},{\"label\":\"New Item\"}]",
"type": "json string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/personFields",
"summary": "Marks multiple fields as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated field IDs to delete",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/personFields/{id}",
"summary": "Marks a field as deleted. For more information on how to delete a custom field, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the field to delete.",
"type": "number"
}
]
}
]
]
},
{
"heading": "Pipelines",
"description": "Pipelines are essentially ordered collections of Stages.",
"endpoint": [
[
{
"method": "GET",
"url": "/pipelines",
"summary": "Returns data about all pipelines",
"parameters": []
}
],
[
{
"method": "GET",
"url": "/pipelines/{id}",
"summary": "Returns data about a specific pipeline. Also returns the summary of the deals in this pipeline across its stages.",
"parameters": [
{
"key": "id",
"description": "ID of the pipeline to fetch.",
"type": "number"
},
{
"key": "totals_convert_currency",
"description": "3-letter currency code of any of the supported currencies. When supplied, per_stages_converted is returned in deals_summary which contains the currency-converted total amounts in the given currency per each stage. You may also set this parameter to 'default_currency' in which case users default currency is used.",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/pipelines/{id}/conversion_statistics",
"summary": "Returns all stage-to-stage conversion and pipeline-to-close rates for given time period.",
"parameters": [
{
"key": "id",
"description": "ID of the pipeline.",
"type": "number"
},
{
"key": "start_date",
"description": "Start of the period. Date in format of YYYY-MM-DD.",
"type": "date"
},
{
"key": "end_date",
"description": "End of the period. Date in format of YYYY-MM-DD.",
"type": "date"
},
{
"key": "user_id",
"description": "ID of the user who's pipeline metrics statistics to fetch. If omitted, the authorized user will be used.",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/pipelines/{id}/deals",
"summary": "Lists deals in a specific pipeline across all its stages",
"parameters": [
{
"key": "id",
"description": "ID of the pipeline to fetch.",
"type": "number"
},
{
"key": "filter_id",
"description": "If supplied, only deals matching the given filter will be returned.",
"type": "number"
},
{
"key": "user_id",
"description": "If supplied, filter_id will not be considered and only deals owned by the given user will be returned. If omitted, deals owned by the authorized user will be returned.",
"type": "number"
},
{
"key": "everyone",
"description": "If supplied, filter_id and user_id will not be considered – instead, deals owned by everyone will be returned.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "stage_id",
"description": "If supplied, only deals within the given stage will be returned.",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "get_summary",
"description": "Whether to include summary of the pipeline in the additional_data or not.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "totals_convert_currency",
"description": "3-letter currency code of any of the supported currencies. When supplied, per_stages_converted is returned inside deals_summary inside additional_data which contains the currency-converted total amounts in the given currency per each stage. You may also set this parameter to 'default_currency' in which case users default currency is used. Only works when get_summary parameter flag is enabled.",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/pipelines/{id}/movement_statistics",
"summary": "Returns statistics for deals movements for given time period.",
"parameters": [
{
"key": "id",
"description": "ID of the pipeline.",
"type": "number"
},
{
"key": "start_date",
"description": "Start of the period. Date in format of YYYY-MM-DD.",
"type": "date"
},
{
"key": "end_date",
"description": "End of the period. Date in format of YYYY-MM-DD.",
"type": "date"
},
{
"key": "user_id",
"description": "ID of the user who's pipeline statistics to fetch. If omitted, the authorized user will be used.",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/pipelines",
"summary": "Adds a new pipeline",
"parameters": [
{
"key": "name",
"description": "Name of the pipeline",
"type": "string"
},
{
"key": "deal_probability",
"description": "Whether deal probability is disabled or enabled for this pipeline.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "order_nr",
"description": "Defines pipelines order. First order(order_nr=0) is the default pipeline.",
"type": "number"
},
{
"key": "active",
"description": "Whether this pipeline will be made inactive (hidden) or active",
"type": "enumerated",
"values": [
"0",
"1"
]
}
]
}
],
[
{
"method": "PUT",
"url": "/pipelines/{id}",
"summary": "Updates pipeline properties",
"parameters": [
{
"key": "id",
"description": "ID of the pipeline to fetch.",
"type": "number"
},
{
"key": "name",
"description": "Name of the pipeline",
"type": "string"
},
{
"key": "deal_probability",
"description": "Whether deal probability is disabled or enabled for this pipeline.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "order_nr",
"description": "Defines pipelines order. First order(order_nr=0) is the default pipeline.",
"type": "number"
},
{
"key": "active",
"description": "Whether this pipeline will be made inactive (hidden) or active",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "DELETE",
"url": "/pipelines/{id}",
"summary": "Marks a pipeline as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the pipeline to delete.",
"type": "number"
}
]
}
]
]
},
{
"heading": "Products",
"description": "Products are the goods or services you are dealing with. Each product can have N different price points - first, each Product can have a price in N different currencies, and secondly, each Product can have N variations of itself, each having N prices different currencies. Note that only one price per variation per currency is supported. Products can be instantiated to Deals. In the context of instatiation, a custom price, quantity, duration and discount can be applied.",
"endpoint": [
[
{
"method": "GET",
"url": "/products",
"summary": "Returns data about all products.",
"parameters": [
{
"key": "user_id",
"description": "If supplied, only products owned by the given user will be returned.",
"type": "number"
},
{
"key": "filter_id",
"description": "ID of the filter to use",
"type": "number"
},
{
"key": "first_char",
"description": "If supplied, only products whose name starts with the specified letter will be returned (case insensitive).",
"type": "string"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/products/find",
"summary": "Returns data about the products that were found. If currency was set in request, prices in that currency are served back.",
"parameters": [
{
"key": "term",
"description": "Search term to look for, minimum 3 characters.",
"type": "string"
},
{
"key": "currency",
"description": "Currency code in which prices should be returned in. If omitted, prices in user's default currency will be returned.",
"type": "string"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/products/{id}",
"summary": "Returns data about a specific product.",
"parameters": [
{
"key": "id",
"description": "ID of the product",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/products/{id}/deals",
"summary": "Returns data about deals that have a product attached to.",
"parameters": [
{
"key": "id",
"description": "ID of the product",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "status",
"description": "Only fetch deals with specific status. If omitted, all not deleted deals are fetched.",
"type": "enumerated",
"values": [
"open",
"won",
"lost",
"deleted",
"all_not_deleted"
]
}
]
}
],
[
{
"method": "GET",
"url": "/products/{id}/files",
"summary": "Lists files associated with a product.",
"parameters": [
{
"key": "id",
"description": "ID of the product",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "include_deleted_files",
"description": "When enabled, the list of files will also include deleted files. Please note that trying to download these files will not work.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "sort",
"description": "Field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, product_id, add_time, update_time, file_name, file_type, file_size, comment.",
"type": "string"
}
]
}
],
[
{
"method": "GET",
"url": "/products/{id}/followers",
"summary": "Lists the followers of a product.",
"parameters": [
{
"key": "id",
"description": "ID of the product",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/products/{id}/permittedUsers",
"summary": "Lists users permitted to access a product.",
"parameters": [
{
"key": "id",
"description": "ID of the product",
"type": "number"
},
{
"key": "access_level",
"description": "If set, filter results by allowed access level. 1 = Read, 2 = Write, 3 = Read+Write",
"type": "enumerated",
"values": [
"",
"1",
"2",
"3"
]
}
]
}
],
[
{
"method": "POST",
"url": "/products",
"summary": "Adds a new product to the products inventory. For more information on how to add a product, see this tutorial.",
"parameters": [
{
"key": "name",
"description": "Name of the product.",
"type": "string"
},
{
"key": "code",
"description": "Product code.",
"type": "string"
},
{
"key": "unit",
"description": "Unit in which this product is sold",
"type": "string"
},
{
"key": "tax",
"description": "Tax percentage",
"type": "number"
},
{
"key": "active_flag",
"description": "Whether this product will be made active or not.",
"type": "enumerated",
"values": [
"0",
"1"
]
},
{
"key": "visible_to",
"description": "Visibility of the product. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.\n\n1\nOwner & followers (private)\n3\nEntire company (shared)",
"type": "enumerated",
"values": [
"",
"1",
"3"
]
},
{
"key": "owner_id",
"description": "ID of the user who will be marked as the owner of this product. When omitted, the authorized user ID will be used.",
"type": "number"
},
{
"key": "prices",
"description": "Array of objects, each containing: currency (string), price (number), cost (number, optional), overhead_cost (number, optional). Note that there can only be one price per product per currency. When 'prices' is omitted altogether, no prices will be set up for the product.",
"type": "json string"
}
]
}
],
[
{
"method": "POST",
"url": "/products/{id}/followers",
"summary": "Adds a follower to a product.",
"parameters": [
{
"key": "id",
"description": "ID of the product",
"type": "number"
},
{
"key": "user_id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "PUT",
"url": "/products/{id}",
"summary": "Updates product data.",
"parameters": [
{
"key": "id",
"description": "ID of the product",
"type": "number"
},
{
"key": "name",
"description": "Name of the product.",
"type": "string"
},
{
"key": "code",
"description": "Product code.",
"type": "string"
},
{
"key": "unit",
"description": "Unit in which this product is sold",
"type": "string"
},
{
"key": "tax",
"description": "Tax percentage",
"type": "number"
},
{
"key": "active_flag",
"description": "Whether this product will be made active or not.",
"type": "enumerated",
"values": [
"0",
"1"
]
},
{
"key": "visible_to",
"description": "Visibility of the product. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.\n\n1\nOwner & followers (private)\n3\nEntire company (shared)",
"type": "enumerated",
"values": [
"",
"1",
"3"
]
},
{
"key": "owner_id",
"description": "ID of the user who will be marked as the owner of this product. When omitted, the authorized user ID will be used.",
"type": "number"
},
{
"key": "prices",
"description": "Array of objects, each containing: currency (string), price (number), cost (number, optional), overhead_cost (number, optional). Note that there can only be one price per product per currency. When 'prices' is omitted altogether, product pricing will not be changed.",
"type": "array"
}
]
}
],
[
{
"method": "DELETE",
"url": "/products/{id}",
"summary": "Marks a product as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the product to delete.",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/products/{id}/followers/{follower_id}",
"summary": "Deletes a follower from a product.",
"parameters": [
{
"key": "id",
"description": "ID of the product",
"type": "number"
},
{
"key": "follower_id",
"description": "ID of the follower",
"type": "number"
}
]
}
]
]
},
{
"heading": "ProductFields",
"description": "ProductFields represent the near-complete schema for a Product in the context of the company of the authorized user. Each company can have a different schema for their Products, with various custom fields. In the context of using ProductFields as a schema for defining the data fields of a Product, it must be kept in mind that some types of custom fields can have additional data fields which are not separate ProductFields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of ProductFields. For example, if there is a monetary field with the key 'ffk9s9' stored on the account, 'ffk9s9' would hold the numeric value of the field, and 'ffk9s9_currency' would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one Product and list its keys.",
"endpoint": [
[
{
"method": "GET",
"url": "/productFields",
"summary": "Returns data about all product fields",
"parameters": []
}
],
[
{
"method": "GET",
"url": "/productFields/{id}",
"summary": "Returns data about a specific product field.",
"parameters": [
{
"key": "id",
"description": "ID of the field to fetch.",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/productFields",
"summary": "Adds a new product field. For more information on adding a new custom field, see this tutorial.",
"parameters": [
{
"key": "name",
"description": "Name of the field",
"type": "string"
},
{
"key": "field_type",
"description": "Type of the field.\n\nvarchar\nText (up to 255 characters)\nvarchar_auto\nAutocomplete text (up to 255 characters)\ntext\nLong text (up to 65k characters)\ndouble\nNumeric value\nmonetary\nMonetary field (has a numeric value and a currency value)\ndate\nDate (format YYYY-MM-DD)\nset\nOptions field with a possibility of having multiple chosen options\nenum\nOptions field with a single possible chosen option\nuser\nUser field (contains a user ID of another Pipedrive user)\norg\nOrganization field (contains an organization ID which is stored on the same account)\npeople\nPerson field (contains a product ID which is stored on the same account)\nphone\nPhone field (up to 255 numbers and/or characters)\ntime\nTime field (format HH:MM:SS)\ntimerange\nTime-range field (has a start time and end time value, both HH:MM:SS)\ndaterange\nDate-range field (has a start date and end date value, both YYYY-MM-DD)",
"type": "enumerated",
"values": [
"varchar",
"varchar_auto",
"text",
"double",
"monetary",
"date",
"set",
"enum",
"user",
"org",
"people",
"phone",
"time",
"timerange",
"daterange"
]
},
{
"key": "options",
"description": "When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array, for example: [\"red\",\"blue\",\"lilac\"]",
"type": "json string"
}
]
}
],
[
{
"method": "PUT",
"url": "/productFields/{id}",
"summary": "Updates a product field. See an example of updating custom fields’ values in this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the field to update.",
"type": "number"
},
{
"key": "name",
"description": "Name of the field",
"type": "string"
},
{
"key": "options",
"description": "When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{\"id\":123,\"label\":\"Existing Item\"},{\"label\":\"New Item\"}]",
"type": "json string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/productFields",
"summary": "Marks multiple fields as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated field IDs to delete",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/productFields/{id}",
"summary": "Marks a field as deleted. For more information on how to delete a custom field, see this tutorial.",
"parameters": [
{
"key": "id",
"description": "ID of the field to delete.",
"type": "number"
}
]
}
]
]
},
{
"heading": "Recents",
"description": "Recent changes across all item types in Pipedrive (deals, persons, etc).",
"endpoint": [
[
{
"method": "GET",
"url": "/recents",
"summary": "Returns data about all recent changes occured after given timestamp.",
"parameters": [
{
"key": "since_timestamp",
"description": "Timestamp in UTC. Format: YYYY-MM-DD HH:MM:SS",
"type": "string"
},
{
"key": "items",
"description": "Multiple selection of item types to include in query (optional)",
"type": "enumerated",
"values": [
"",
"activity",
"activityType",
"deal",
"delete_log",
"file",
"filter",
"note",
"person",
"organization",
"pipeline",
"product",
"stage",
"user"
]
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
]
]
},
{
"heading": "Roles",
"description": "Roles are a part of the Visibility groups’ feature that allow the Admin user to categorize other users and dictate what items they will be allowed access to see.",
"endpoint": [
[
{
"method": "GET",
"url": "/roles",
"summary": "",
"parameters": [
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/roles/{id}",
"summary": "",
"parameters": [
{
"key": "id",
"description": "ID of the role",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/roles/{id}/assignments",
"summary": "List assignments for a role",
"parameters": [
{
"key": "id",
"description": "ID of the role",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/roles/{id}/roles",
"summary": "",
"parameters": [
{
"key": "id",
"description": "ID of the role",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/roles/{id}/settings",
"summary": "",
"parameters": [
{
"key": "id",
"description": "ID of the role",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/roles",
"summary": "",
"parameters": [
{
"key": "parent_role_id",
"description": "",
"type": "number"
},
{
"key": "name",
"description": "",
"type": "string"
}
]
}
],
[
{
"method": "POST",
"url": "/roles/{id}/assignments",
"summary": "Add assignment for a role",
"parameters": [
{
"key": "id",
"description": "ID of the role",
"type": "number"
},
{
"key": "user_id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/roles/{id}/settings",
"summary": "",
"parameters": [
{
"key": "id",
"description": "ID of the role",
"type": "number"
},
{
"key": "setting_key",
"description": "",
"type": "enumerated",
"values": [
"deal_default_visibility",
"org_default_visibility",
"person_default_visibility",
"product_default_visibility",
"deal_access_level",
"org_access_level",
"person_access_level",
"product_access_level"
]
},
{
"key": "value",
"description": "Possible values for default_visibility settings: 0...1; for access_level settings: 1...7",
"type": "enumerated",
"values": [
"0",
"1",
"2",
"3",
"4",
"5",
"6",
"7"
]
}
]
}
],
[
{
"method": "PUT",
"url": "/roles/{id}",
"summary": "",
"parameters": [
{
"key": "id",
"description": "ID of the role",
"type": "number"
},
{
"key": "parent_role_id",
"description": "",
"type": "number"
},
{
"key": "name",
"description": "",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/roles/{id}",
"summary": "",
"parameters": [
{
"key": "id",
"description": "ID of the role",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/roles/{id}/assignments",
"summary": "Delete assignment from a role",
"parameters": [
{
"key": "id",
"description": "ID of the role",
"type": "number"
},
{
"key": "user_id",
"description": "ID of the user",
"type": "number"
}
]
}
]
]
},
{
"heading": "SearchResults",
"description": "Ordered reference objects, pointing to either Deals, Persons, Organizations, Files or Products.",
"endpoint": [
[
{
"method": "GET",
"url": "/searchResults",
"summary": "Performs a search across the account and returns SearchResults.",
"parameters": [
{
"key": "term",
"description": "Search term to look for, minimum 2 characters.",
"type": "string"
},
{
"key": "item_type",
"description": "Search for items of exact type. If omitted, all types of items are searched.",
"type": "enumerated",
"values": [
"",
"deal",
"person",
"organization",
"product",
"file"
]
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
},
{
"key": "exact_match",
"description": "When enabled, only full exact matches against the given term are returned. The minimum 2 character limit for the term is discarded when exact_match is enabled. It will only work if search term is 30 characters or less.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "GET",
"url": "/searchResults/field",
"summary": "Performs a search from a specific field's values. Results can be either the distinct values of the field (useful for searching autocomplete field values), or actual items IDs (deals, persons, organizations or products). Works only with the following field types: varchar, varchar_auto, double, address, text, phone, date.",
"parameters": [
{
"key": "term",
"description": "Search term to look for, minimum 2 characters.",
"type": "string"
},
{
"key": "exact_match",
"description": "When enabled, only full exact matches against the given term are returned. By default, term can be present anywhere in the resulting field values to be considered a match. The minimum 2 character limit for the term is discarded when exact_match is enabled.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "field_type",
"description": "Type of the field to perform the search from.",
"type": "enumerated",
"values": [
"dealField",
"personField",
"organizationField",
"productField"
]
},
{
"key": "field_key",
"description": "Key of the field to search from. Field key can be obtained by fetching the list of fields using any of fields API GET methods (dealFields, personFields, ..).",
"type": "string"
},
{
"key": "return_field_key",
"description": "Name of the field in search results from which the search was performed. When omitted, 'value' will be used. You may want to set this parameter to match the field_key.",
"type": "string"
},
{
"key": "return_item_ids",
"description": "Whether to return matching items IDs in search results. When omitted or set to 0, only distinct values of the searched field are returned. When enabled, the return_field_key parameter is ignored and the results include the searched field as its own key.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
]
]
},
{
"heading": "Stages",
"description": "Stage is a logical component of a Pipeline, and essentially a bucket that can hold a number of Deals. In the context of the Pipeline a stage belongs to, it has an order number which defines the order of stages in that Pipeline.",
"endpoint": [
[
{
"method": "GET",
"url": "/stages",
"summary": "Returns data about all stages",
"parameters": [
{
"key": "pipeline_id",
"description": "ID of the pipeline to fetch stages for. If omitted, stages for all pipelines will be fetched.",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/stages/{id}",
"summary": "Returns data about a specific stage",
"parameters": [
{
"key": "id",
"description": "ID of the stage",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/stages/{id}/deals",
"summary": "Lists deals in a specific stage",
"parameters": [
{
"key": "id",
"description": "ID of the stage",
"type": "number"
},
{
"key": "filter_id",
"description": "If supplied, only deals matching the given filter will be returned.",
"type": "number"
},
{
"key": "user_id",
"description": "If supplied, filter_id will not be considered and only deals owned by the given user will be returned. If omitted, deals owned by the authorized user will be returned.",
"type": "number"
},
{
"key": "everyone",
"description": "If supplied, filter_id and user_id will not be considered – instead, deals owned by everyone will be returned.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/stages",
"summary": "Adds a new stage, returns the ID upon success.",
"parameters": [
{
"key": "name",
"description": "Name of the stage",
"type": "string"
},
{
"key": "pipeline_id",
"description": "ID of the pipeline to add stage to.",
"type": "number"
},
{
"key": "deal_probability",
"description": "Deal success probability percentage. Used/shown when deal weighted values are used.",
"type": "number"
},
{
"key": "rotten_flag",
"description": "Whether deals in this stage can become rotten.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "rotten_days",
"description": "Number of days the deals not updated in this stage would become rotten. Applies only if rotten_flag is set.",
"type": "number"
}
]
}
],
[
{
"method": "PUT",
"url": "/stages/{id}",
"summary": "Updates the properties of a stage.",
"parameters": [
{
"key": "id",
"description": "ID of the stage",
"type": "number"
},
{
"key": "name",
"description": "Name of the stage",
"type": "string"
},
{
"key": "pipeline_id",
"description": "ID of the pipeline this stage belongs to.",
"type": "number"
},
{
"key": "order_nr",
"description": "An order number for this stage. Order numbers should be used to order the stages in the pipeline.",
"type": "number"
},
{
"key": "deal_probability",
"description": "Deal success probability percentage. Used/shown when deal weighted values are used.",
"type": "number"
},
{
"key": "rotten_flag",
"description": "Whether deals in this stage can become rotten.",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
},
{
"key": "rotten_days",
"description": "Number of days the deals not updated in this stage would become rotten. Applies only if rotten_flag is set.",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/stages",
"summary": "Marks multiple stages as deleted.",
"parameters": [
{
"key": "ids",
"description": "Comma-separated stage IDs to delete",
"type": "number"
}
]
}
],
[
{
"method": "DELETE",
"url": "/stages/{id}",
"summary": "Marks a stage as deleted.",
"parameters": [
{
"key": "id",
"description": "ID of the stage to delete",
"type": "number"
}
]
}
]
]
},
{
"heading": "Users",
"description": "Users are people with access to your Pipedrive account. A user may belong to one or many Pipedrive accounts, so deleting a user from one Pipedrive account will not remove the user from the data store if he/she is connected to multiple accounts. Users should not be confused with Persons.",
"endpoint": [
[
{
"method": "GET",
"url": "/users",
"summary": "Returns data about all users within the company",
"parameters": []
}
],
[
{
"method": "GET",
"url": "/users/find",
"summary": "Finds users by their name.",
"parameters": [
{
"key": "term",
"description": "Search term to look for",
"type": "string"
},
{
"key": "search_by_email",
"description": "When enabled, term will only be matched against email addresses of users. Default: false",
"type": "enumerated",
"values": [
"",
"0",
"1"
]
}
]
}
],
[
{
"method": "GET",
"url": "/users/me",
"summary": "Returns data about an authorized user within the company with bound company data: company ID, company name, and domain. Note that the 'locale' property means 'Date and number format' in the Pipedrive settings, not the chosen language.",
"parameters": []
}
],
[
{
"method": "GET",
"url": "/users/{id}",
"summary": "Returns data about a specific user within the company",
"parameters": [
{
"key": "id",
"description": "ID of the user to fetch.",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/users/{id}/blacklistedEmails",
"summary": "Lists blacklisted email addresses of a specific user. Blacklisted emails are such that will not get synced in to Pipedrive when using the built-in Mailbox.",
"parameters": [
{
"key": "id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/users/{id}/followers",
"summary": "Lists followers of a specific user.",
"parameters": [
{
"key": "id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/users/{id}/permissions",
"summary": "List aggregated permissions over all assigned permission sets for a user",
"parameters": [
{
"key": "id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/users/{id}/roleAssignments",
"summary": "List role assignments for a user",
"parameters": [
{
"key": "id",
"description": "ID of the user",
"type": "number"
},
{
"key": "start",
"description": "Pagination start",
"type": "number"
},
{
"key": "limit",
"description": "Items shown per page",
"type": "number"
}
]
}
],
[
{
"method": "GET",
"url": "/users/{id}/roleSettings",
"summary": "List settings of user's assigned role",
"parameters": [
{
"key": "id",
"description": "ID of the user",
"type": "number"
}
]
}
],
[
{
"method": "POST",
"url": "/users",
"summary": "Adds a new user to the company, returns the ID upon success.",
"parameters": [
{
"key": "name",
"description": "Name of the user",
"type": "string"
},
{
"key": "email",
"description": "Email of the user",
"type": "string"
},
{
"key": "active_flag",
"description": "Whether the user is active or not. 0 = Not activated, 1 = Activated",
"type": "enumerated",
"values": [
"0",
"1"
]
}
]
}
],
[
{
"method": "POST",
"url": "/users/{id}/blacklistedEmails",
"summary": "Add blacklisted email address for a specific user.",
"parameters": [
{
"key": "id",
"description": "ID of the user",
"type": "number"
},
{
"key": "address",
"description": "Email address to blacklist (can contain * for wildcards, e.g. *@example.com, or john*@ex*.com)",
"type": "string"
}
]
}
],
[
{
"method": "POST",
"url": "/users/{id}/roleAssignments",
"summary": "Add role assignment for a user",
"parameters": [
{
"key": "id",
"description": "ID of the user",
"type": "number"
},
{
"key": "role_id",
"description": "ID of the role",
"type": "number"
}
]
}
],
[
{
"method": "PUT",
"url": "/users/{id}",
"summary": "Updates the properties of a user. Currently, only active_flag can be updated.",
"parameters": [
{
"key": "id",
"description": "ID of the user",
"type": "number"
},
{
"key": "active_flag",
"description": "Whether the user is active or not. 0 = Not activated, 1 = Activated",
"type": "enumerated",
"values": [
"0",
"1"
]
}
]
}
],
[
{
"method": "DELETE",
"url": "/users/{id}/roleAssignments",
"summary": "Delete a role assignment for a user",
"parameters": [
{
"key": "id",
"description": "ID of the user",
"type": "number"
},
{
"key": "role_id",
"description": "ID of the role",
"type": "number"
}
]
}
]
]
},
{
"heading": "UserConnections",
"description": "Manage user connections.",
"endpoint": [
[
{
"method": "GET",
"url": "/userConnections",
"summary": "Returns data about all connections for authorized user.",
"parameters": []
}
]
]
},
{
"heading": "UserSettings",
"description": "User settings",
"endpoint": [
[
{
"method": "GET",
"url": "/userSettings",
"summary": "Lists settings of authorized user.",
"parameters": []
}
]
]
},
{
"heading": "Webhooks",
"description": "See https://pipedrive.readme.io/docs/guide-for-webhooks for more info about webhooks.",
"endpoint": [
[
{
"method": "GET",
"url": "/webhooks",
"summary": "Returns data about all webhooks of a company.",
"parameters": []
}
],
[
{
"method": "POST",
"url": "/webhooks",
"summary": "Creates a new webhook and returns its details. Note that specifying an event which triggers the webhook combines 2 parameters - 'event_action' and 'event_object'. E.g., use '*.*' for getting notifications about all events, 'added.deal' for any newly added deals, 'deleted.persons' for any deleted persons, etc. See https://pipedrive.readme.io/docs/guide-for-webhooks for more details.",
"parameters": [
{
"key": "subscription_url",
"description": "A full, valid, publicly accessible URL. Determines where to send the notifications. Please note that you cannot use Pipedrive API endpoints as the subscription_url.",
"type": "string"
},
{
"key": "event_action",
"description": "Type of action to receive notifications about. Wildcard will match all supported actions.",
"type": "enumerated",
"values": [
"added",
"updated",
"merged",
"deleted",
"*"
]
},
{
"key": "event_object",
"description": "Type of object to receive notifications about. Wildcard will match all supported objects.",
"type": "enumerated",
"values": [
"activity",
"activityType",
"deal",
"note",
"organization",
"person",
"pipeline",
"product",
"stage",
"user",
"*"
]
},
{
"key": "user_id",
"description": "ID of the user this webhook will be authorized with. If not set, current authorized user will be used. Note that this does not filter only certain user's events — rather, this specifies the user's permissions under which each event is checked. Events about objects the selected user is not entitled to access are not sent. If you want to receive notifications for all events, a top-level admin user should be used.",
"type": "number"
},
{
"key": "http_auth_user",
"description": "HTTP basic auth username of the subscription URL endpoint (if required).",
"type": "string"
},
{
"key": "http_auth_password",
"description": "HTTP basic auth password of the subscription URL endpoint (if required).",
"type": "string"
}
]
}
],
[
{
"method": "DELETE",
"url": "/webhooks/{id}",
"summary": "Deletes the specified webhook.",
"parameters": [
{
"key": "id",
"description": "ID of the webhook to delete.",
"type": "number"
}
]
}
]
]
}
]
Raw
scraper.js
// Navigate to https://developers.pipedrive.com/docs/api/v1/ and run this in the dev tools.
// `schema` is an array with the data in.
const schema = []
for (const resource of document.querySelectorAll('li.resource')) {
const heading = resource.querySelector('div.heading > h2').innerText
const description = resource.querySelector('div.markdown.action-summary > p').innerText
const e = []
for (const endpoint of resource.querySelectorAll('.endpoints > .endpoint')) {
const o = []
for (const operation of endpoint.querySelectorAll('ul.operations > .operation')) {
const method = operation.querySelector('.heading .http_method a').innerText
const url = operation.querySelector('.heading .path a').innerText
const summary = operation.querySelector('.action-summary p') ? operation.querySelector('.action-summary p').innerText : ''
const p = []
for (const param of operation.querySelectorAll('.operation-params > .parameter-item')) {
const key = param.querySelector('.parameter__name') ? param.querySelector('.parameter__name').innerText : ''
const description = param.querySelector('.parameter__description') ? param.querySelector('.parameter__description').innerText : ''
const type = param.querySelector('.parameter__type code') ? param.querySelector('.parameter__type code').innerText : ''
if (key || description || type) {
if (type === 'enumerated') {
const v = []
for (const value of param.querySelectorAll('select > option')) {
v.push(value.value)
}
p.push({
key,
description,
type,
values: v,
})
} else {
p.push({
key,
description,
type,
values: null,
})
}
}
}
o.push({
method,
url,
summary,
parameters: p,
})
}
e.push(o)
}
schema.push({
heading,
description,
endpoint: e,
})
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment