Pipedrive API Reference

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.

API v1

Request

GET

/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

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

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }
- ▶
  "related_objects":{ ... }

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.

API v1

Request

GET

/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

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

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.

View quick guide: /v1 to /v2 migration

API v1

API v2

Endpoint is in beta

Request

GET

/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

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }
- ▶
  "additional_data":{ ... }

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.

API v1

Request

GET

/v1/organizations/{id}

Path parameters

integer

required

The ID of the organization

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }
- ▶
  "additional_data":{ ... }
- ▶
  "related_objects":{ ... }

List activities associated with an organization

Lists activities associated with an organization.

API v1

Request

GET

/v1/organizations/{id}/activities

Path parameters

integer

required

The ID of the organization

Query parameters

start

integer

Pagination start

Default

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

exclude

string

A comma-separated string of activity IDs to exclude from result

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List updates about organization field values

Lists updates about field values of an organization.

API v1

Request

GET

/v1/organizations/{id}/changelog

Path parameters

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

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List deals associated with an organization

Lists deals associated with an organization.

API v1

Request

GET

/v1/organizations/{id}/deals

Path parameters

integer

required

The ID of the organization

Query parameters

start

integer

Pagination start

Default

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

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }
- ▶
  "related_objects":{ ... }

List files attached to an organization

Lists files associated with an organization.

API v1

Request

GET

/v1/organizations/{id}/files

Path parameters

integer

required

The ID of the organization

Query parameters

start

integer

Pagination start

Default

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

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List updates about an organization

Lists updates about an organization.

API v1

Request

GET

/v1/organizations/{id}/flow

Path parameters

integer

required

The ID of the organization

Query parameters

start

integer

Pagination start

Default

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

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }
- ▶
  "related_objects":{ ... }

List followers of an organization

Lists the followers of an organization.

API v1

Request

GET

/v1/organizations/{id}/followers

Path parameters

integer

required

The ID of the organization

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List mail messages associated with an organization

Lists mail messages associated with an organization.

API v1

Request

GET

/v1/organizations/{id}/mailMessages

Path parameters

integer

required

The ID of the organization

Query parameters

start

integer

Pagination start

Default

limit

integer

Items shown per page

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }

List permitted users

List users permitted to access an organization.

API v1

Request

GET

/v1/organizations/{id}/permittedUsers

Path parameters

integer

required

The ID of the organization

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]

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.

API v1

Request

GET

/v1/organizations/{id}/persons

Path parameters

integer

required

The ID of the organization

Query parameters

start

integer

Pagination start

Default

limit

integer

Items shown per page

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":[ ... ]
- ▶
  "additional_data":{ ... }
- ▶
  "related_objects":{ ... }

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.

API v1

Request

POST

/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. 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.

label

integer

The ID of the label.

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

Response

201

Created

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }
- ▶
  "related_objects":{ ... }

Add a follower to an organization

Adds a follower to an organization.

API v1

Request

POST

/v1/organizations/{id}/followers

Path parameters

integer

required

The ID of the organization

Body parameters

application/json

user_id

integer

required

The ID of the user

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Update an organization

Updates the properties of an organization.

API v1

Request

PUT

/v1/organizations/{id}

Path parameters

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 ID of the label.

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

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }
- ▶
  "related_objects":{ ... }

Merge two organizations

Merges an organization with another organization. For more information, see the tutorial for merging two organizations.

API v1

Request

PUT

/v1/organizations/{id}/merge

Path parameters

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

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Delete multiple organizations in bulk

Marks multiple organizations as deleted. After 30 days, the organizations will be permanently deleted.

API v1

Request

DELETE

/v1/organizations

Query parameters

ids

string

required

The comma-separated IDs that will be deleted

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

Delete an organization

Marks an organization as deleted. After 30 days, the organization will be permanently deleted.

API v1

Request

DELETE

/v1/organizations/{id}

Path parameters

integer

required

The ID of the organization

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }

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.

API v1

Request

DELETE

/v1/organizations/{id}/followers/{follower_id}

Path parameters

integer

required

The ID of the organization

follower_id

integer

required

The ID of the follower

Response

200

Expand all

Copy code

- "success":true
- ▶
  "data":{ ... }