Organizations
Organizations are companies and other kinds of organizations you are making deals with. Persons can be associated with organizations so that each organization can contain one or more persons.
Get all organizations
Returns data about all organizations.
Cost
10
Request
/api/v2/organizations
Query parameters
filter_id
integer
If supplied, only organizations 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 organization owned by the specified user are returned. If filter_id is provided, this is ignored.
updated_since
string
If set, only organizations 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 organizations 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
Values
next_activity_id
last_activity_id
open_deals_count
related_open_deals_count
closed_deals_count
related_closed_deals_count
email_messages_count
people_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
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 organization
Returns the details of a specific organization.
Cost
1
Request
/api/v2/organizations/{id}
Path parameters
id
integer
required
The ID of the organization
Query parameters
include_fields
string
Optional comma separated string array of additional fields to include
Values
next_activity_id
last_activity_id
open_deals_count
related_open_deals_count
closed_deals_count
related_closed_deals_count
email_messages_count
people_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
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 organization field values
Lists updates about field values of an organization.
Cost
20
Request
/v1/organizations/{id}/changelog
Path parameters
id
integer
required
The ID of the organization
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 an organization
Lists files associated with an organization.
Cost
20
Request
/v1/organizations/{id}/files
Path parameters
id
integer
required
The ID of the organization
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 an organization
Lists updates about an organization.
Cost
40
Request
/v1/organizations/{id}/flow
Path parameters
id
integer
required
The ID of the organization
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
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List followers of an organization
Lists users who are following the organization.
Cost
10
Request
/api/v2/organizations/{id}/followers
Path parameters
id
integer
required
The ID of the organization
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 an organization
Lists changelogs about users have followed the organization.
Cost
10
Request
/api/v2/organizations/{id}/followers/changelog
Path parameters
id
integer
required
The ID of the organization
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 an organization
Lists mail messages associated with an organization.
Cost
20
Request
/v1/organizations/{id}/mailMessages
Path parameters
id
integer
required
The ID of the organization
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 an organization.
Cost
10
Request
/v1/organizations/{id}/permittedUsers
Path parameters
id
integer
required
The ID of the organization
Response
OK
Expand allCopy code- true
- [ ... ]▶
Search organizations
Searches all organizations by name, address, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.
Cost
20
Request
/api/v2/organizations/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
address
custom_fields
notes
name
exact_match
boolean
When enabled, only full exact matches against the given term are returned. It is not case sensitive.
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 organization
Adds a new organization.
Cost
5
Request
/api/v2/organizations
Body parameters
application/json
name
string
The name of the organization
owner_id
integer
The ID of the user who owns the organization
add_time
string
The creation date and time of the organization
update_time
string
The last updated date and time of the organization
visible_to
integer
The visibility of the organization
label_ids
array
The IDs of labels assigned to the organization
address
object
The address of the organization
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 an organization
Adds a user as a follower to the organization.
Cost
5
Request
/api/v2/organizations/{id}/followers
Path parameters
id
integer
required
The ID of the organization
Body parameters
application/json
user_id
integer
required
The ID of the user to add as a follower
Response
Created
Expand allCopy code- true
- { ... }▶
Merge two organizations
Merges an organization with another organization. For more information, see the tutorial for merging two organizations.
Cost
40
Request
/v1/organizations/{id}/merge
Path parameters
id
integer
required
The ID of the organization
Body parameters
application/json
merge_with_id
integer
required
The ID of the organization that the organization will be merged with
Response
OK
Expand allCopy code- true
- { ... }▶
Update a organization
Updates the properties of a organization.
Cost
5
Request
/api/v2/organizations/{id}
Path parameters
id
integer
required
The ID of the organization
Body parameters
application/json
name
string
The name of the organization
owner_id
integer
The ID of the user who owns the organization
add_time
string
The creation date and time of the organization
update_time
string
The last updated date and time of the organization
visible_to
integer
The visibility of the organization
label_ids
array
The IDs of labels assigned to the organization
address
object
The address of the organization
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 organization
Marks a organization as deleted. After 30 days, the organization will be permanently deleted.
Cost
3
Request
/api/v2/organizations/{id}
Path parameters
id
integer
required
The ID of the organization
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a follower from an organization
Deletes a user follower from the organization.
Cost
3
Request
/api/v2/organizations/{id}/followers/{follower_id}
Path parameters
id
integer
required
The ID of the organization
follower_id
integer
required
The ID of the following user
Response
OK
Expand allCopy code- true
- { ... }▶