{
"opencollection": "1.0.0",
"info": {
"name": "Pipedrive API v1 Activities Persons API",
"version": "1.0.0"
},
"items": [
{
"info": {
"name": "Persons",
"type": "folder"
},
"items": [
{
"info": {
"name": "List updates about person field values",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id/changelog",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
},
{
"name": "cursor",
"value": "",
"type": "query",
"description": "For pagination, the marker (an opaque string value) representing the first item on the next page"
},
{
"name": "limit",
"value": "",
"type": "query",
"description": "Items shown per page"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Lists updates about field values of a person."
},
{
"info": {
"name": "List files attached to a person",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id/files",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
},
{
"name": "start",
"value": "",
"type": "query",
"description": "Pagination start"
},
{
"name": "limit",
"value": "",
"type": "query",
"description": "Items shown per page. Please note that a maximum value of 100 is allowed."
},
{
"name": "sort",
"value": "",
"type": "query",
"description": "Supported fields: `id`, `update_time`"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Lists files associated with a person."
},
{
"info": {
"name": "List updates about a person",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id/flow",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
},
{
"name": "start",
"value": "",
"type": "query",
"description": "Pagination start"
},
{
"name": "limit",
"value": "",
"type": "query",
"description": "Items shown per page"
},
{
"name": "all_changes",
"value": "",
"type": "query",
"description": "Whether to show custom field updates or not. 1 = Include custom field changes. If omitted returns changes without custom field updates."
},
{
"name": "items",
"value": "",
"type": "query",
"description": "A comma-separated string for filtering out item specific updates. (Possible values - call, activity, plannedActivity, change, note, deal, file, dealChange, personChange, organizationChange, follower, dealFollower, personFollower, organizationFollower, participant, comment, mailMessage, mailMessageWithAttachment, invoice, document, marketing_campaign_stat, marketing_status_change)."
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Lists updates about a person.
If a company uses the [Campaigns product](https://pipedrive.readme.io/docs/campaigns-in-pipedrive-api), then this endpoint's response will also include updates for the `marketing_status` field."
},
{
"info": {
"name": "List followers of a person",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id/followers",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Lists the followers of a person."
},
{
"info": {
"name": "Add a follower to a person",
"type": "http"
},
"http": {
"method": "POST",
"url": "https://api.pipedrive.com/v1/persons/:id/followers",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
}
],
"body": {
"type": "json",
"data": "{}"
},
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Adds a follower to a person."
},
{
"info": {
"name": "Delete a follower from a person",
"type": "http"
},
"http": {
"method": "DELETE",
"url": "https://api.pipedrive.com/v1/persons/:id/followers/:follower_id",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
},
{
"name": "follower_id",
"value": "",
"type": "path",
"description": "The ID of the relationship between the follower and the person"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Deletes a follower from a person."
},
{
"info": {
"name": "List mail messages associated with a person",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id/mailMessages",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
},
{
"name": "start",
"value": "",
"type": "query",
"description": "Pagination start"
},
{
"name": "limit",
"value": "",
"type": "query",
"description": "Items shown per page"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Lists mail messages associated with a person."
},
{
"info": {
"name": "Merge two persons",
"type": "http"
},
"http": {
"method": "PUT",
"url": "https://api.pipedrive.com/v1/persons/:id/merge",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
}
],
"body": {
"type": "json",
"data": "{}"
},
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Merges a person with another person. For more information, see the tutorial for merging two persons."
},
{
"info": {
"name": "List permitted users",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id/permittedUsers",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "List users permitted to access a person."
},
{
"info": {
"name": "Get picture of a person",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id/picture",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Returns the picture associated with a person. The picture URLs include both 128x128 and 512x512 pixel versions."
},
{
"info": {
"name": "Add person picture",
"type": "http"
},
"http": {
"method": "POST",
"url": "https://api.pipedrive.com/v1/persons/:id/picture",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
}
],
"body": {
"type": "multipart-form",
"data": [
{
"name": "file",
"type": "text",
"value": ""
},
{
"name": "crop_x",
"type": "text",
"value": ""
},
{
"name": "crop_y",
"type": "text",
"value": ""
},
{
"name": "crop_width",
"type": "text",
"value": ""
},
{
"name": "crop_height",
"type": "text",
"value": ""
}
]
},
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Adds 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."
},
{
"info": {
"name": "Delete person picture",
"type": "http"
},
"http": {
"method": "DELETE",
"url": "https://api.pipedrive.com/v1/persons/:id/picture",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Deletes a person’s picture."
},
{
"info": {
"name": "List products associated with a person",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id/products",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
},
{
"name": "start",
"value": "",
"type": "query",
"description": "Pagination start"
},
{
"name": "limit",
"value": "",
"type": "query",
"description": "Items shown per page"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Lists products associated with a person."
},
{
"info": {
"name": "Get all persons",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons",
"params": [
{
"name": "filter_id",
"value": "",
"type": "query",
"description": "If supplied, only persons matching the specified filter are returned"
},
{
"name": "ids",
"value": "",
"type": "query",
"description": "Optional comma separated string array of up to 100 entity ids to fetch. If filter_id is provided, this is ignored. If any of the requested entities do not exist or are not visible, they are not included in the response."
},
{
"name": "owner_id",
"value": "",
"type": "query",
"description": "If supplied, only persons owned by the specified user are returned. If filter_id is provided, this is ignored."
},
{
"name": "org_id",
"value": "",
"type": "query",
"description": "If supplied, only persons linked to the specified organization are returned. If filter_id is provided, this is ignored."
},
{
"name": "deal_id",
"value": "",
"type": "query",
"description": "If supplied, only persons linked to the specified deal are returned. If filter_id is provided, this is ignored."
},
{
"name": "updated_since",
"value": "",
"type": "query",
"description": "If set, only persons with an `update_time` later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z."
},
{
"name": "updated_until",
"value": "",
"type": "query",
"description": "If set, only persons with an `update_time` earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z."
},
{
"name": "sort_by",
"value": "",
"type": "query",
"description": "The field to sort by. Supported fields: `id`, `update_time`, `add_time`."
},
{
"name": "sort_direction",
"value": "",
"type": "query",
"description": "The sorting direction. Supported values: `asc`, `desc`."
},
{
"name": "include_fields",
"value": "",
"type": "query",
"description": "Optional comma separated string array of additional fields to include. `marketing_status` and `doi_status` can only be included if the company has marketing app enabled."
},
{
"name": "custom_fields",
"value": "",
"type": "query",
"description": "Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.
A maximum of 15 keys is allowed."
},
{
"name": "include_option_labels",
"value": "",
"type": "query",
"description": "When provided with a 'true' value, single option and multiple option custom fields values contain objects in the form of '{ id: number, label: string }' instead of plain id"
},
{
"name": "include_labels",
"value": "",
"type": "query",
"description": "When provided with 'true' value, response will include an array of label objects in the form of '{ id: number, label: string }'"
},
{
"name": "limit",
"value": "",
"type": "query",
"description": "For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed."
},
{
"name": "cursor",
"value": "",
"type": "query",
"description": "For pagination, the marker (an opaque string value) representing the first item on the next page"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Returns data about all persons. Fields `ims`, `postal_address`, `notes`, `birthday`, and `job_title` are only included if contact sync is enabled for the company."
},
{
"info": {
"name": "Add a new person",
"type": "http"
},
"http": {
"method": "POST",
"url": "https://api.pipedrive.com/v1/persons",
"body": {
"type": "json",
"data": "{}"
},
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Adds a new person. If the company uses the [Campaigns product](https://pipedrive.readme.io/docs/campaigns-in-pipedrive-api), then this endpoint will also accept and return the `marketing_status` field."
},
{
"info": {
"name": "Get details of a person",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
},
{
"name": "include_fields",
"value": "",
"type": "query",
"description": "Optional comma separated string array of additional fields to include. `marketing_status` and `doi_status` can only be included if the company has marketing app enabled."
},
{
"name": "custom_fields",
"value": "",
"type": "query",
"description": "Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.
A maximum of 15 keys is allowed."
},
{
"name": "include_option_labels",
"value": "",
"type": "query",
"description": "When provided with a 'true' value, single option and multiple option custom fields values contain objects in the form of '{ id: number, label: string }' instead of plain id"
},
{
"name": "include_labels",
"value": "",
"type": "query",
"description": "When provided with 'true' value, response will include an array of label objects in the form of '{ id: number, label: string }'"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Returns the details of a specific person. Fields `ims`, `postal_address`, `notes`, `birthday`, and `job_title` are only included if contact sync is enabled for the company."
},
{
"info": {
"name": "Update a person",
"type": "http"
},
"http": {
"method": "PATCH",
"url": "https://api.pipedrive.com/v1/persons/:id",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
}
],
"body": {
"type": "json",
"data": "{}"
},
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Updates the properties of a person.
If the company uses the [Campaigns product](https://pipedrive.readme.io/docs/campaigns-in-pipedrive-api), then this endpoint will also accept and return the `marketing_status` field."
},
{
"info": {
"name": "Delete a person",
"type": "http"
},
"http": {
"method": "DELETE",
"url": "https://api.pipedrive.com/v1/persons/:id",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Marks a person as deleted. After 30 days, the person will be permanently deleted."
},
{
"info": {
"name": "List followers changelog of a person",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/:id/followers/changelog",
"params": [
{
"name": "id",
"value": "",
"type": "path",
"description": "The ID of the person"
},
{
"name": "limit",
"value": "",
"type": "query",
"description": "For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed."
},
{
"name": "cursor",
"value": "",
"type": "query",
"description": "For pagination, the marker (an opaque string value) representing the first item on the next page"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Lists changelogs about users have followed the person."
},
{
"info": {
"name": "Search persons",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pipedrive.com/v1/persons/search",
"params": [
{
"name": "term",
"value": "",
"type": "query",
"description": "The search term to look for. Minimum 2 characters (or 1 if using `exact_match`). Please note that the search term has to be URL encoded."
},
{
"name": "fields",
"value": "",
"type": "query",
"description": "A comma-separated string array. The fields to perform the search from. Defaults to all of them. Only the following custom field types are searchable: `address`, `varchar`, `text`, `varchar_auto`, `double`, `monetary` and `phone`. Read more about searching by custom fields here."
},
{
"name": "exact_match",
"value": "",
"type": "query",
"description": "When enabled, only full exact matches against the given term are returned. It is not case sensitive."
},
{
"name": "organization_id",
"value": "",
"type": "query",
"description": "Will filter persons by the provided organization ID. The upper limit of found persons associated with the organization is 2000."
},
{
"name": "include_fields",
"value": "",
"type": "query",
"description": "Supports including optional fields in the results which are not provided by default"
},
{
"name": "limit",
"value": "",
"type": "query",
"description": "For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed."
},
{
"name": "cursor",
"value": "",
"type": "query",
"description": "For pagination, the marker (an opaque string value) representing the first item on the next page"
}
],
"auth": {
"type": "apikey",
"key": "x-api-token",
"value": "{{x-api-token}}",
"placement": "header"
}
},
"docs": "Searches all persons by name, email, phone, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope. Found persons can be filtered by organization ID."
}
]
}
],
"bundled": true
}