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
Returns all persons.
Request
/v1/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
The 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
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).
Response
OK
Expand all
Copy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
Get all persons (BETA)
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.
Request
/v1/persons/collection
Query parameters
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)
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
Search persons
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.
Request
/api/v2/persons/search
Query parameters
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
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Get details of a person
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.
Request
/v1/persons/{id}
Path parameters
id
integer
required
The ID of the person
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
- { ... }▶
List activities associated with a person
Lists activities associated with a person.
Request
/v1/persons/{id}/activities
Path parameters
id
integer
required
The ID of the 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
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List updates about person field values
Lists updates about field values of a person.
Request
/v1/persons/{id}/changelog
Path parameters
id
integer
required
The ID of the person
Query parameters
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
limit
integer
Items shown per page
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List deals associated with a person
Lists deals associated with a person.
Request
/v1/persons/{id}/deals
Path parameters
id
integer
required
The ID of the person
Query parameters
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).
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List files attached to a person
Lists files associated with a person.
Request
/v1/persons/{id}/files
Path parameters
id
integer
required
The ID of the person
Query parameters
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.
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List updates about a person
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.
Request
/v1/persons/{id}/flow
Path parameters
id
integer
required
The ID of the 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 - 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).
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List followers of a person
Lists the followers of a person.
Request
/v1/persons/{id}/followers
Path parameters
id
integer
required
The ID of the person
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List mail messages associated with a person
Lists mail messages associated with a person.
Request
/v1/persons/{id}/mailMessages
Path parameters
id
integer
required
The ID of the person
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List permitted users
List users permitted to access a person.
Request
/v1/persons/{id}/permittedUsers
Path parameters
id
integer
required
The ID of the person
Response
OK
Expand allCopy code- true
- [ ... ]▶
List products associated with a person
Lists products associated with a person.
Request
/v1/persons/{id}/products
Path parameters
id
integer
required
The ID of the person
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
Add a person
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.
Request
/v1/persons
Body parameters
application/json
name
string
required
The name of the person
owner_id
integer
The 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
The ID of the organization this person will belong to
array
An email address as a string or an array of email objects related to the person. The structure of the array is as follows: [{ "value": "[email protected]", "primary": "true", "label": "main" }]. Please note that only value is required.
phone
array
A phone number supplied as a string or an array of phone objects related to the person. The structure of the array is as follows: [{ "value": "12345", "primary": "true", "label": "mobile" }]. Please note that only value is required.
label
integer
The ID of the label.
visible_to
string
The visibility of the person. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.
Essential / Advanced plan
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Professional / Enterprise plan
| Value | Description |
|---|---|
1 | Owner only |
3 | Owner's visibility group |
5 | Owner's visibility group and sub-groups |
7 | Entire company |
Values
1
3
5
7
marketing_status
If the person does not have a valid email address, then the marketing status is not set and no_consent is returned for the marketing_status value when the new person is created. If the change is forbidden, the status will remain unchanged for every call that tries to modify the marketing status. Please be aware that it is only allowed once to change the marketing status from an old status to a new one.
| Value | Description |
|---|---|
no_consent | The customer has not given consent to receive any marketing communications |
unsubscribed | The customers have unsubscribed from ALL marketing communications |
subscribed | The customers are subscribed and are counted towards marketing caps |
archived | The customers with subscribed status can be moved to archived to save consent, but they are not paid for |
Values
no_consent
unsubscribed
subscribed
archived
add_time
string
The optional creation date & time of the person in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS
Response
Created
Expand allCopy code- true
- { ... }▶
- { ... }▶
Add a follower to a person
Adds a follower to a person.
Request
/v1/persons/{id}/followers
Path parameters
id
integer
required
The ID of the person
Body parameters
application/json
user_id
integer
required
The ID of the user
Response
OK
Expand allCopy code- true
- { ... }▶
Add person picture
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.
Request
/v1/persons/{id}/picture
Path parameters
id
integer
required
The ID of the 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
The width of the cropping area (in pixels)
crop_height
integer
The height of the cropping area (in pixels)
Response
OK
Expand allCopy code- true
- { ... }▶
Update a person
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.
Request
/v1/persons/{id}
Path parameters
id
integer
required
The ID of the person
Body parameters
application/json
name
string
The name of the person
owner_id
integer
The 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
The ID of the organization this person will belong to
array
An email address as a string or an array of email objects related to the person. The structure of the array is as follows: [{ "value": "[email protected]", "primary": "true", "label": "main" }]. Please note that only value is required.
phone
array
A phone number supplied as a string or an array of phone objects related to the person. The structure of the array is as follows: [{ "value": "12345", "primary": "true", "label": "mobile" }]. Please note that only value is required.
label
integer
The ID of the label.
visible_to
string
The visibility of the person. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.
Essential / Advanced plan
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Professional / Enterprise plan
| Value | Description |
|---|---|
1 | Owner only |
3 | Owner's visibility group |
5 | Owner's visibility group and sub-groups |
7 | Entire company |
Values
1
3
5
7
marketing_status
If the person does not have a valid email address, then the marketing status is not set and no_consent is returned for the marketing_status value when the new person is created. If the change is forbidden, the status will remain unchanged for every call that tries to modify the marketing status. Please be aware that it is only allowed once to change the marketing status from an old status to a new one.
| Value | Description |
|---|---|
no_consent | The customer has not given consent to receive any marketing communications |
unsubscribed | The customers have unsubscribed from ALL marketing communications |
subscribed | The customers are subscribed and are counted towards marketing caps |
archived | The customers with subscribed status can be moved to archived to save consent, but they are not paid for |
Values
no_consent
unsubscribed
subscribed
archived
add_time
string
The optional creation date & time of the person in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Merge two persons
Merges a person with another person. For more information, see the tutorial for merging two persons.
Request
/v1/persons/{id}/merge
Path parameters
id
integer
required
The ID of the person
Body parameters
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.
Response
OK
Expand allCopy code- true
- { ... }▶
Delete multiple persons in bulk
Marks multiple persons as deleted. After 30 days, the persons will be permanently deleted.
Request
/v1/persons
Query parameters
ids
string
required
The comma-separated IDs that will be deleted
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a person
Marks a person as deleted. After 30 days, the person will be permanently deleted.
Request
/v1/persons/{id}
Path parameters
id
integer
required
The ID of the person
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a follower from a person
Deletes a follower from a person.
Request
/v1/persons/{id}/followers/{follower_id}
Path parameters
id
integer
required
The ID of the person
follower_id
integer
required
The ID of the follower
Response
OK
Expand allCopy code- true
- { ... }▶
Delete person picture
Deletes a person’s picture.
Request
/v1/persons/{id}/picture
Path parameters
id
integer
required
The ID of the person
Response
OK
Expand allCopy code- true
- { ... }▶