Persons
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.
Get all persons
/v1/persons
Returns all persons
Query parameters
user_id
integer
If supplied, only persons owned by the given user will be returned. However, filter_id takes precedence over user_id when both are supplied.
filter_id
integer
ID of the filter to use.
first_char
string
If supplied, only persons whose name starts with the specified letter will be returned (case insensitive).
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
sort
string
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).
Response
success
Expand all
Copy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
Search persons
/v1/persons/search
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.
Query parameters
term
string
required
The search term to look for. Minimum 2 characters (or 1 if using exact_match).
fields
string
A comma-separated string array. The fields to perform the search from. Defaults to all of them.
Values
custom_fields
notes
phone
name
exact_match
boolean
When enabled, only full exact matches against the given term are returned. It is not case sensitive.
Values
true
false
organization_id
integer
Will filter Deals by the provided Organization ID. The upper limit of found Deals associated with the Organization is 2000.
include_fields
string
Supports including optional fields in the results which are not provided by default.
Values
person.picture
start
integer
Pagination start. Note that the pagination is based on main results and does not include related items when using search_for_related_items parameter.
Default
0
limit
integer
Items shown per page
Response
success
Expand allCopy code- true
- { ... }▶
- { ... }▶
Find persons by name
/v1/persons/find
Deprecated endpoint
This endpoint is deprecated. Please use /v1/persons/search or /v1/itemSearch instead.
Searches all persons by their name.
Query parameters
term
string
required
Search term to look for
org_id
integer
ID of the organization person is associated with.
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
search_by_email
number
When enabled, term will only be matched against email addresses of people. Default: false
Values
0
1
Response
success
Get details of a person
/v1/persons/{id}
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.
Path parameters
id
integer
required
ID of a person
Response
success
Expand allCopy code- true
- { ... }▶
- { ... }▶
- { ... }▶
List activities associated with a person
/v1/persons/{id}/activities
Lists activities associated with a person.
Path parameters
id
integer
required
ID of a person
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
done
number
Whether the activity is done or not. 0 = Not done, 1 = Done. If omitted returns both Done and Not done activities.
Values
0
1
exclude
string
A comma-separated string of activity IDs to exclude from result
Response
success
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List deals associated with a person
/v1/persons/{id}/deals
Lists deals associated with a person.
Path parameters
id
integer
required
ID of a person
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
status
string
Only fetch deals with specific status. If omitted, all not deleted deals are fetched.
Default
all_not_deleted
Values
open
won
lost
deleted
all_not_deleted
sort
string
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).
Response
success
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List files attached to a person
/v1/persons/{id}/files
Lists files associated with a person.
Path parameters
id
integer
required
ID of a person
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
include_deleted_files
number
When enabled, the list of files will also include deleted files. Please note that trying to download these files will not work.
Values
0
1
sort
string
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.
Response
success
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List updates about a person
/v1/persons/{id}/flow
Lists updates about a person.
Path parameters
id
integer
required
ID of a person
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
all_changes
string
Whether to show custom field updates or not. 1 = Include custom field changes. If omitted returns changes without custom field updates.
items
string
A comma-separated string for filtering out item specific updates. (Possible values - activity, plannedActivity, note, file, change, deal, follower, participant, mailMessage, mailMessageWithAttachment, invoice, activityFile, document)
Response
Get the Person Updates
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List followers of a person
/v1/persons/{id}/followers
Lists the followers of a person.
Path parameters
id
integer
required
ID of a person
Response
success
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List mail messages associated with a person
/v1/persons/{id}/mailMessages
Lists mail messages associated with a person.
Path parameters
id
integer
required
ID of a person
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
Response
success
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List permitted users
/v1/persons/{id}/permittedUsers
List users permitted to access a person
Path parameters
id
integer
required
ID of a person
Response
success
Expand allCopy code- true
- [ ... ]▶
List products associated with a person
/v1/persons/{id}/products
Lists products associated with a person.
Path parameters
id
integer
required
ID of a person
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
Response
success
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
Add a person
/v1/persons
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.
Body parameters
application/json
name
string
Person name
owner_id
integer
ID of the user who will be marked as the owner of this person. When omitted, the authorized user ID will be used.
org_id
integer
ID of the organization this person will belong to.
array
Email addresses (one or more) associated with the person, presented in the same manner as received by GET request of a person.
phone
array
Phone numbers (one or more) associated with the person, presented in the same manner as received by GET request of a person.
visible_to
Visibility of the person. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.
| Value | Description |
|---|---|
1 | Owner & followers (private) |
3 | Entire company (shared) |
Values
1
3
add_time
string
Optional creation date & time of the person in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS
Response
success
Expand allCopy code- true
- { ... }▶
- { ... }▶
Add a follower to a person
/v1/persons/{id}/followers
Adds a follower to a person.
Path parameters
id
integer
required
ID of a person
Body parameters
application/x-www-form-urlencoded
user_id
integer
required
ID of the user
Response
success
Expand allCopy code- true
- { ... }▶
Add person picture
/v1/persons/{id}/picture
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.
Path parameters
id
integer
required
ID of a person
Body parameters
multipart/form-data
file
string
required
One image supplied in the multipart/form-data encoding.
Format
binary
crop_x
integer
X coordinate to where start cropping form (in pixels)
crop_y
integer
Y coordinate to where start cropping form (in pixels)
crop_width
integer
Width of cropping area (in pixels)
crop_height
integer
Height of cropping area (in pixels)
Response
success
Expand allCopy code- true
- { ... }▶
Update a person
/v1/persons/{id}
Updates the properties of a person. For more information on how to update a person, see this tutorial.
Path parameters
id
integer
required
ID of a person
Body parameters
application/json
name
string
Person name
owner_id
integer
ID of the user who will be marked as the owner of this person. When omitted, the authorized user ID will be used.
org_id
integer
ID of the organization this person will belong to.
array
Email addresses (one or more) associated with the person, presented in the same manner as received by GET request of a person.
phone
array
Phone numbers (one or more) associated with the person, presented in the same manner as received by GET request of a person.
visible_to
Visibility of the person. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.
| Value | Description |
|---|---|
1 | Owner & followers (private) |
3 | Entire company (shared) |
Values
1
3
Response
success
Expand allCopy code- true
- { ... }▶
- { ... }▶
Merge two persons
/v1/persons/{id}/merge
Merges a person with another person. For more information on how to merge two persons, see this tutorial.
Path parameters
id
integer
required
ID of a person
Body parameters
application/x-www-form-urlencoded
merge_with_id
integer
required
The ID of the Person that will not be overwritten. This Person’s data will be prioritized in case of conflict with the other Person.
Response
success
Expand allCopy code- true
- { ... }▶
Delete multiple persons in bulk
/v1/persons
Marks multiple persons as deleted.
Query parameters
ids
string
Comma-separated IDs that will be deleted
Response
success
Expand allCopy code- true
- { ... }▶
Delete a person
/v1/persons/{id}
Marks a person as deleted.
Path parameters
id
integer
required
ID of a person
Response
success
Expand allCopy code- true
- { ... }▶
Deletes a follower from a person.
/v1/persons/{id}/followers/{follower_id}
Delete a follower from a person
Path parameters
id
integer
required
ID of a person
follower_id
integer
required
ID of the follower
Response
success
Expand allCopy code- true
- { ... }▶
Delete person picture
/v1/persons/{id}/picture
Delete person picture
Path parameters
id
integer
required
ID of a person
Response
success
Expand allCopy code- true
- { ... }▶