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
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 all organizations collection
Returns all organizations. Please note that only global admins (those with global permissions) can access this endpoint. Users with regular permissions will receive a 403 response. Read more about global permissions here.
This endpoint has been deprecated. Please use GET /api/v2/organizations instead.
Cost
10
Request
/v1/organizations/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 organizations owned by the given user will be returned
first_char
string
If supplied, only organizations whose name starts with the specified letter will be returned (case-insensitive)
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
- { ... }▶
- { ... }▶
Get details of an 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
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 activities associated with an organization
Lists activities associated with an organization.
This endpoint has been deprecated. Please use GET /api/v2/activities?org_id={id} instead.
Cost
20
Request
/v1/organizations/{id}/activities
Path parameters
id
integer
required
The ID of the organization
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 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 deals associated with an organization
Lists deals associated with an organization.
This endpoint has been deprecated. Please use GET /api/v2/deals?org_id={id} instead.
Cost
20
Request
/v1/organizations/{id}/deals
Path parameters
id
integer
required
The ID of the organization
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).
only_primary_association
number
If set, only deals that are directly associated to the organization are fetched. If not set (default), all deals are fetched that are either directly or indirectly related to the organization. Indirect relations include relations through custom, organization-type fields and through persons of the given organization.
Values
0
1
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 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
- [ ... ]▶
List persons of an organization
Lists persons associated with an organization.
If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.
This endpoint has been deprecated. Please use GET /api/v2/persons?org_id={id} instead.
Cost
20
Request
/v1/organizations/{id}/persons
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 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
- [ ... ]▶
- { ... }▶
Add an 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
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
- { ... }▶
Update an 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
Response
OK
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
- { ... }▶
Delete multiple organizations in bulk
Marks multiple organizations as deleted. After 30 days, the organizations will be permanently deleted.
This endpoint has been deprecated. Please use DELETE /api/v2/organizations/{id} instead.
Cost
10
Request
/v1/organizations
Query parameters
ids
string
required
The comma-separated IDs that will be deleted
Response
OK
Expand allCopy code- true
- { ... }▶
Delete an 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
- { ... }▶