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 all organizations.
Request
/v1/organizations
Query parameters
user_id
integer
If supplied, only organizations 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 organizations 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 organizations (BETA)
Returns all organizations. 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/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.
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 an organization. Note that this also returns some additional fields which are not present when asking for all organizations. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the key value of organizationFields.
Request
/v1/organizations/{id}
Path parameters
id
integer
required
The ID of the organization
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
- { ... }▶
List activities associated with an organization
Lists activities associated with an organization.
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.
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.
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.
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
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 an organization
Lists updates about an organization.
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 the followers of an organization.
Request
/v1/organizations/{id}/followers
Path parameters
id
integer
required
The ID of the organization
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List mail messages associated with an organization
Lists mail messages associated with an organization.
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.
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.
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
- [ ... ]▶
- { ... }▶
- { ... }▶
Add an organization
Adds a new organization. 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 organizationFields and look for key values. For more information, see the tutorial for adding an organization.
Request
/v1/organizations
Body parameters
application/json
name
string
required
The name of the organization
add_time
string
The optional creation date & time of the organization in UTC. Format: YYYY-MM-DD HH:MM:SS
owner_id
integer
The ID of the user who will be marked as the owner of this organization. When omitted, the authorized user ID will be used.
label
integer
The label assigned to the organization. When the label field is updated, the label_ids field value will be overwritten by the label field value.
label_ids
array
The IDs of labels assigned to the organization. When the label_ids field is updated, the label field value will be set to the first value of the label_ids field.
visible_to
string
The visibility of the organization. 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
Response
Created
Expand allCopy code- true
- { ... }▶
- { ... }▶
Add a follower to an organization
Adds a follower to an organization.
Request
/v1/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
Response
OK
Expand allCopy code- true
- { ... }▶
Update an organization
Updates the properties of an organization.
Request
/v1/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 will be marked as the owner of this organization. When omitted, the authorized user ID will be used.
label
integer
The label assigned to the organization. When the label field is updated, the label_ids field value will be overwritten by the label field value.
label_ids
array
The IDs of labels assigned to the organization. When the label_ids field is updated, the label field value will be set to the first value of the label_ids field.
visible_to
string
The visibility of the organization. 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
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.
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.
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 an organization as deleted. After 30 days, the organization will be permanently deleted.
Request
/v1/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 follower from an organization. You can retrieve the follower_id from the List followers of an organization endpoint.
Request
/v1/organizations/{id}/followers/{follower_id}
Path parameters
id
integer
required
The ID of the organization
follower_id
integer
required
The ID of the follower
Response
OK
Expand allCopy code- true
- { ... }▶