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.
/v1/organizations
Returns all organizations.
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).
OK
/v1/organizations/search
Searches all organizations by name, address, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.
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.
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.
Values
true
false
start
integer
Pagination start. Note that the pagination is based on main results and does not include related items when using search_for_related_items
parameter.
Default
0
limit
integer
Items shown per page
OK
/v1/organizations/{id}
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.
id
integer
required
The ID of the organization
OK
/v1/organizations/{id}/activities
Lists activities associated with an organization.
id
integer
required
The ID of the organization
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
OK
/v1/organizations/{id}/deals
Lists deals associated with an organization.
id
integer
required
The ID of the organization
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
OK
/v1/organizations/{id}/files
Lists files associated with an organization.
id
integer
required
The ID of the organization
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
.
OK
/v1/organizations/{id}/flow
Lists updates about an organization.
id
integer
required
The ID of the organization
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)
OK
/v1/organizations/{id}/followers
Lists the followers of an organization.
id
integer
required
The ID of the organization
OK
/v1/organizations/{id}/mailMessages
Lists mail messages associated with an organization.
id
integer
required
The ID of the organization
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
/v1/organizations/{id}/permittedUsers
List users permitted to access an organization.
id
integer
required
The ID of the organization
OK
/v1/organizations/{id}/persons
Lists persons associated with an organization.
If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status
field.
id
integer
required
The ID of the organization
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
/v1/organizations
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.
application/json
name
string
required
The name of the organization
add_time
string
The optional creation date & time of the organization in UTC. Requires admin user API token. 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.
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.
Value | Description |
---|---|
1 | Owner & followers |
3 | Entire company |
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
Created
/v1/organizations/{id}/followers
Adds a follower to an organization.
id
integer
required
The ID of the organization
application/json
user_id
integer
required
The ID of the user
OK
/v1/organizations/{id}
Updates the properties of an organization.
id
integer
required
The ID of the organization
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.
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.
Value | Description |
---|---|
1 | Owner & followers |
3 | Entire company |
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
OK
/v1/organizations/{id}/merge
Merges an organization with another organization. For more information, see the tutorial for merging two organizations.
id
integer
required
The ID of the organization
application/json
merge_with_id
integer
required
The ID of the organization that the organization will be merged with
OK
/v1/organizations
Marks multiple organizations as deleted. After 30 days, the organizations will be permanently deleted.
ids
string
required
The comma-separated IDs that will be deleted
OK
/v1/organizations/{id}
Marks an organization as deleted. After 30 days, the organization will be permanently deleted.
id
integer
required
The ID of the organization
OK
/v1/organizations/{id}/followers/{follower_id}
Deletes a follower from an organization. You can retrieve the follower_id
from the List followers of an organization endpoint.
id
integer
required
The ID of the organization
follower_id
integer
required
The ID of the follower
OK