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 data about all persons. Fields ims, postal_address, notes, birthday, and job_title are only included if contact sync is enabled for the company.
Cost
10
Request
/api/v2/persons
Query parameters
filter_id
integer
If supplied, only persons matching the specified filter are returned
ids
string
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.
owner_id
integer
If supplied, only persons 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.
deal_id
integer
If supplied, only persons linked to the specified deal 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
smart_bcc_email
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
Response
OK
Expand all
Copy code- true
- [ ... ]▶
- { ... }▶
Get details of a person
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.
Cost
1
Request
/api/v2/persons/{id}
Path parameters
id
integer
required
The ID of the person
Query parameters
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
smart_bcc_email
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.
Response
OK
Expand allCopy code- true
- { ... }▶
List updates about person field values
Lists updates about field values of a person.
Cost
20
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 files attached to a person
Lists files associated with a person.
Cost
20
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. Please note that a maximum value of 100 is allowed.
sort
string
Supported fields: id, update_time
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.
Cost
40
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 users who are following the person.
Cost
10
Request
/api/v2/persons/{id}/followers
Path parameters
id
integer
required
The ID of the person
Query parameters
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
- [ ... ]▶
- { ... }▶
List followers changelog of a person
Lists changelogs about users have followed the person.
Cost
10
Request
/api/v2/persons/{id}/followers/changelog
Path parameters
id
integer
required
The ID of the person
Query parameters
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
- [ ... ]▶
- { ... }▶
List mail messages associated with a person
Lists mail messages associated with a person.
Cost
20
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.
Cost
10
Request
/v1/persons/{id}/permittedUsers
Path parameters
id
integer
required
The ID of the person
Response
OK
Expand allCopy code- true
- [ ... ]▶
Get picture of a person
Returns the picture associated with a person. The picture URLs include both 128x128 and 512x512 pixel versions.
Cost
1
Request
/api/v2/persons/{id}/picture
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.
Cost
20
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
- [ ... ]▶
- { ... }▶
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.
Cost
20
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
- { ... }▶
- { ... }▶
Add a new person
Adds a new person. If the company uses the Campaigns product, then this endpoint will also accept and return the marketing_status field.
Cost
5
Request
/api/v2/persons
Body parameters
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
marketing_status
string
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
custom_fields
object
An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes
Response
OK
Expand allCopy code- true
- { ... }▶
Add a follower to a person
Adds a user as a follower to the person.
Cost
5
Request
/api/v2/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 to add as a follower
Response
Created
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.
Cost
10
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
- { ... }▶
Merge two persons
Merges a person with another person. For more information, see the tutorial for merging two persons.
Cost
40
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
- { ... }▶
Update a person
Updates the properties of a person.
If the company uses the Campaigns product, then this endpoint will also accept and return the marketing_status field.
Cost
5
Request
/api/v2/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 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
marketing_status
string
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
custom_fields
object
An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a person
Marks a person as deleted. After 30 days, the person will be permanently deleted.
Cost
3
Request
/api/v2/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 user follower from the person.
Cost
3
Request
/api/v2/persons/{id}/followers/{follower_id}
Path parameters
id
integer
required
The ID of the person
follower_id
integer
required
The ID of the following user
Response
OK
Expand allCopy code- true
- { ... }▶
Delete person picture
Deletes a person’s picture.
Cost
6
Request
/v1/persons/{id}/picture
Path parameters
id
integer
required
The ID of the person
Response
OK
Expand allCopy code- true
- { ... }▶