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

Copy link
Copy to clipboard
GET

/v1/organizations

Returns all 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
200

OK

Expand all
Copy code
    • true
    • [ ... ]
      • { ... }
        • { ... }

        Search organizations

        Copy link
        Copy to clipboard
        GET

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

        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.

        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

        Response
        200

        OK

        Expand all
        Copy code
          • true
          • { ... }
            • { ... }

            Get details of an organization

            Copy link
            Copy to clipboard
            GET

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

            Path parameters

            id

            integer

            required

            The ID of the organization

            Response
            200

            OK

            Expand all
            Copy code
              • true
              • { ... }

              List activities associated with an organization

              Copy link
              Copy to clipboard
              GET

              /v1/organizations/{id}/activities

              Lists activities associated with an organization.

              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
              200

              OK

              Expand all
              Copy code
                • true
                • [ ... ]
                  • { ... }

                  List deals associated with an organization

                  Copy link
                  Copy to clipboard
                  GET

                  /v1/organizations/{id}/deals

                  Lists deals associated with an organization.

                  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
                  200

                  OK

                  Expand all
                  Copy code
                    • true
                    • [ ... ]
                      • { ... }
                        • { ... }

                        List files attached to an organization

                        Copy link
                        Copy to clipboard
                        GET

                        /v1/organizations/{id}/files

                        Lists files associated with an organization.

                        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
                        200

                        OK

                        Expand all
                        Copy code
                          • true
                          • [ ... ]
                            • { ... }

                            List updates about an organization

                            Copy link
                            Copy to clipboard
                            GET

                            /v1/organizations/{id}/flow

                            Lists updates about an organization.

                            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
                            200

                            OK

                            Expand all
                            Copy code
                              • true
                              • [ ... ]
                                • { ... }
                                  • { ... }

                                  List followers of an organization

                                  Copy link
                                  Copy to clipboard
                                  GET

                                  /v1/organizations/{id}/followers

                                  Lists the followers of an organization.

                                  Path parameters

                                  id

                                  integer

                                  required

                                  The ID of the organization

                                  Response
                                  200

                                  OK

                                  Expand all
                                  Copy code
                                    • true
                                    • [ ... ]
                                      • { ... }

                                      List mail messages associated with an organization

                                      Copy link
                                      Copy to clipboard
                                      GET

                                      /v1/organizations/{id}/mailMessages

                                      Lists mail messages associated with an organization.

                                      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
                                      200

                                      OK

                                      Expand all
                                      Copy code
                                        • true
                                        • [ ... ]
                                          • { ... }

                                          List permitted users

                                          Copy link
                                          Copy to clipboard
                                          GET

                                          /v1/organizations/{id}/permittedUsers

                                          List users permitted to access an organization.

                                          Path parameters

                                          id

                                          integer

                                          required

                                          The ID of the organization

                                          Response
                                          200

                                          OK

                                          Expand all
                                          Copy code
                                            • true
                                            • [ ... ]

                                            List persons of an organization

                                            Copy link
                                            Copy to clipboard
                                            GET

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

                                            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
                                            200

                                            OK

                                            Expand all
                                            Copy code
                                              • true
                                              • [ ... ]
                                                • { ... }
                                                  • { ... }

                                                  Add an organization

                                                  Copy link
                                                  Copy to clipboard
                                                  POST

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

                                                  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.

                                                  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

                                                  ValueDescription
                                                  1Owner & followers
                                                  3Entire company

                                                  Professional / Enterprise plan

                                                  ValueDescription
                                                  1Owner only
                                                  3Owner's visibility group
                                                  5Owner's visibility group and sub-groups
                                                  7Entire company

                                                  Values

                                                  1

                                                  3

                                                  5

                                                  7

                                                  Response
                                                  201

                                                  Created

                                                  Expand all
                                                  Copy code
                                                    • true
                                                    • { ... }
                                                      • { ... }

                                                      Add a follower to an organization

                                                      Copy link
                                                      Copy to clipboard
                                                      POST

                                                      /v1/organizations/{id}/followers

                                                      Adds a follower to an organization.

                                                      Path parameters

                                                      id

                                                      integer

                                                      required

                                                      The ID of the organization

                                                      Body parameters

                                                      application/json

                                                      user_id

                                                      integer

                                                      required

                                                      The ID of the user

                                                      Response
                                                      200

                                                      OK

                                                      Expand all
                                                      Copy code
                                                        • true
                                                        • { ... }

                                                        Update an organization

                                                        Copy link
                                                        Copy to clipboard
                                                        PUT

                                                        /v1/organizations/{id}

                                                        Updates the properties of an organization.

                                                        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.

                                                        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

                                                        ValueDescription
                                                        1Owner & followers
                                                        3Entire company

                                                        Professional / Enterprise plan

                                                        ValueDescription
                                                        1Owner only
                                                        3Owner's visibility group
                                                        5Owner's visibility group and sub-groups
                                                        7Entire company

                                                        Values

                                                        1

                                                        3

                                                        5

                                                        7

                                                        Response
                                                        200

                                                        OK

                                                        Expand all
                                                        Copy code
                                                          • true
                                                          • { ... }
                                                            • { ... }

                                                            Merge two organizations

                                                            Copy link
                                                            Copy to clipboard
                                                            PUT

                                                            /v1/organizations/{id}/merge

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

                                                            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
                                                            200

                                                            OK

                                                            Expand all
                                                            Copy code
                                                              • true
                                                              • { ... }

                                                              Delete multiple organizations in bulk

                                                              Copy link
                                                              Copy to clipboard
                                                              DELETE

                                                              /v1/organizations

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

                                                              Query parameters

                                                              ids

                                                              string

                                                              required

                                                              The comma-separated IDs that will be deleted

                                                              Response
                                                              200

                                                              OK

                                                              Expand all
                                                              Copy code
                                                                • true
                                                                • { ... }

                                                                Delete an organization

                                                                Copy link
                                                                Copy to clipboard
                                                                DELETE

                                                                /v1/organizations/{id}

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

                                                                Path parameters

                                                                id

                                                                integer

                                                                required

                                                                The ID of the organization

                                                                Response
                                                                200

                                                                OK

                                                                Expand all
                                                                Copy code
                                                                  • true
                                                                  • { ... }

                                                                  Delete a follower from an organization

                                                                  Copy link
                                                                  Copy to clipboard
                                                                  DELETE

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

                                                                  Path parameters

                                                                  id

                                                                  integer

                                                                  required

                                                                  The ID of the organization

                                                                  follower_id

                                                                  integer

                                                                  required

                                                                  The ID of the follower

                                                                  Response
                                                                  200

                                                                  OK

                                                                  Expand all
                                                                  Copy code
                                                                    • true
                                                                    • { ... }

                                                                    Subscribe to Pipedrive’s Developer Newsletter