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.
Returns all persons.
/api/v2/persons
filter_id
integer
If supplied, only persons matching the specified filter are returned
owner_id
integer
If supplied, only person owned by the specified user are returned. If filter_id is provided, this is ignored.
org_id
integer
If supplied, only persons linked to the specified organization are returned. If filter_id is provided, this is ignored.
updated_since
string
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.
updated_until
string
If set, only persons with an update_time
earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.
sort_by
string
The field to sort by. Supported fields: id
, update_time
, add_time
.
Default
id
Values
id
update_time
add_time
sort_direction
string
The sorting direction. Supported values: asc
, desc
.
Default
asc
Values
asc
desc
include_fields
string
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.
Values
next_activity_id
last_activity_id
open_deals_count
related_open_deals_count
closed_deals_count
related_closed_deals_count
participant_open_deals_count
participant_closed_deals_count
email_messages_count
activities_count
done_activities_count
undone_activities_count
files_count
notes_count
followers_count
won_deals_count
related_won_deals_count
lost_deals_count
related_lost_deals_count
last_incoming_mail_time
last_outgoing_mail_time
marketing_status
doi_status
custom_fields
string
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.
limit
integer
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.
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
OK
Returns all persons. This is a cursor-paginated endpoint that is currently in BETA. For more information, please refer to our documentation on pagination. Please note that only global admins (those with global permissions) can access these endpoints. Users with regular permissions will receive a 403 response. Read more about global permissions here.
/v1/persons/collection
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
limit
integer
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.
since
string
The time boundary that points to the start of the range of data. Datetime in ISO 8601 format. E.g. 2022-11-01 08:55:59. Operates on the update_time
field.
until
string
The time boundary that points to the end of the range of data. Datetime in ISO 8601 format. E.g. 2022-11-01 08:55:59. Operates on the update_time
field.
owner_id
integer
If supplied, only persons owned by the given user will be returned
first_char
string
If supplied, only persons whose name starts with the specified letter will be returned (case-insensitive)
OK
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.
/api/v2/persons/search
term
string
required
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.
fields
string
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.
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.
organization_id
integer
Will filter persons by the provided organization ID. The upper limit of found persons 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
limit
integer
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.
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
OK
Returns the 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.
If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status
field.
/api/v2/persons/{id}
id
integer
required
The ID of the person
include_fields
string
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.
Values
next_activity_id
last_activity_id
open_deals_count
related_open_deals_count
closed_deals_count
related_closed_deals_count
participant_open_deals_count
participant_closed_deals_count
email_messages_count
activities_count
done_activities_count
undone_activities_count
files_count
notes_count
followers_count
won_deals_count
related_won_deals_count
lost_deals_count
related_lost_deals_count
last_incoming_mail_time
last_outgoing_mail_time
marketing_status
doi_status
custom_fields
string
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.
OK
Lists activities associated with a person.
/v1/persons/{id}/activities
id
integer
required
The ID of the person
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
OK
Lists updates about field values of a person.
/v1/persons/{id}/changelog
id
integer
required
The ID of the person
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
limit
integer
Items shown per page
OK
Lists deals associated with a person.
/v1/persons/{id}/deals
id
integer
required
The ID of the person
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
status
string
Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included.
Default
all_not_deleted
Values
open
won
lost
deleted
all_not_deleted
sort
string
The 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).
OK
Lists files associated with a person.
/v1/persons/{id}/files
id
integer
required
The ID of the person
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
sort
string
The 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
.
OK
Lists updates about a person.
If a company uses the Campaigns product, then this endpoint's response will also include updates for the marketing_status
field.
/v1/persons/{id}/flow
id
integer
required
The ID of the person
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 - 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).
OK
Lists the followers of a person.
/v1/persons/{id}/followers
id
integer
required
The ID of the person
OK
Lists mail messages associated with a person.
/v1/persons/{id}/mailMessages
id
integer
required
The ID of the person
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
List users permitted to access a person.
/v1/persons/{id}/permittedUsers
id
integer
required
The ID of the person
OK
Lists products associated with a person.
/v1/persons/{id}/products
id
integer
required
The ID of the person
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
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.
If a company uses the Campaigns product, then this endpoint will also accept and return the data.marketing_status
field.
/api/v2/persons
application/json
name
string
The name of the person
owner_id
integer
The ID of the user who owns the person
org_id
integer
The ID of the organization linked to the person
add_time
string
The creation date and time of the person
update_time
string
The last updated date and time of the person
emails
array
The emails of the person
phones
array
The phones of the person
visible_to
integer
The visibility of the person
label_ids
array
The IDs of labels assigned to the person
OK
Adds a follower to a person.
/v1/persons/{id}/followers
id
integer
required
The ID of the person
application/json
user_id
integer
required
The ID of the user
OK
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.
/v1/persons/{id}/picture
id
integer
required
The ID of the person
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
The width of the cropping area (in pixels)
crop_height
integer
The height of the cropping area (in pixels)
OK
Updates the properties of a person. For more information, see the tutorial for updating a person.
If a company uses the Campaigns product, then this endpoint will also accept and return the data.marketing_status
field.
/api/v2/persons/{id}
id
integer
required
The ID of the person
application/json
name
string
The name of the person
owner_id
integer
The ID of the user who owns the person
org_id
integer
The ID of the organization linked to the person
add_time
string
The creation date and time of the person
update_time
string
The last updated date and time of the person
emails
array
The emails of the person
phones
array
The phones of the person
visible_to
integer
The visibility of the person
label_ids
array
The IDs of labels assigned to the person
OK
Merges a person with another person. For more information, see the tutorial for merging two persons.
/v1/persons/{id}/merge
id
integer
required
The ID of the person
application/json
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.
OK
Marks multiple persons as deleted. After 30 days, the persons will be permanently deleted.
/v1/persons
ids
string
required
The comma-separated IDs that will be deleted
OK
Marks a person as deleted. After 30 days, the person will be permanently deleted.
/api/v2/persons/{id}
id
integer
required
The ID of the person
OK
Deletes a follower from a person.
/v1/persons/{id}/followers/{follower_id}
id
integer
required
The ID of the person
follower_id
integer
required
The ID of the follower
OK
Deletes a person’s picture.
/v1/persons/{id}/picture
id
integer
required
The ID of the person
OK