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

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

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

success

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

        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

        success

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

            Find organizations by name

            Copy link
            Copy to clipboard
            GET

            /v1/organizations/find

            Deprecated endpoint

            This endpoint is deprecated. Please use /v1/organizations/search or /v1/itemSearch instead.
            Searches all organizations by their name.

            Query parameters

            term

            string

            required

            Search term to look for

            start

            integer

            Pagination start

            Default

            0

            limit

            integer

            Items shown per page

            Response
            200

            success

            Get details of an organization

            Copy link
            Copy to clipboard
            GET

            /v1/organizations/{id}

            Returns 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

            success

            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

              success

              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 specific status. If omitted, all not deleted deals are fetched.

                  Default

                  all_not_deleted

                  Values

                  open

                  won

                  lost

                  deleted

                  all_not_deleted

                  sort

                  string

                  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

                  success

                  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

                        include_deleted_files

                        number

                        When enabled, the list of files will also include deleted files. Please note that trying to download these files will not work.

                        Values

                        0

                        1

                        sort

                        string

                        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

                        success

                        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

                            Get the Organization Updates

                            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

                                  success

                                  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

                                      success

                                      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

                                          success

                                          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.

                                            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

                                            success

                                            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 on how to add an organization, see this tutorial.

                                                  Body parameters

                                                  application/json

                                                  name

                                                  string

                                                  Organization name

                                                  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

                                                  Visibility of the organization. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.

                                                  ValueDescription
                                                  1Owner & followers (private)
                                                  3Entire company (shared)

                                                  Values

                                                  1

                                                  3

                                                  add_time

                                                  string

                                                  Optional creation date & time of the organization in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

                                                  Response
                                                  200

                                                  success

                                                  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

                                                      success

                                                      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

                                                        Organization name

                                                        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

                                                        Visibility of the organization. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.

                                                        ValueDescription
                                                        1Owner & followers (private)
                                                        3Entire company (shared)

                                                        Values

                                                        1

                                                        3

                                                        Response
                                                        200

                                                        success

                                                        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 on how to merge two organizations, see this tutorial.

                                                            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

                                                            success

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

                                                              Delete multiple organizations in bulk

                                                              Copy link
                                                              Copy to clipboard
                                                              DELETE

                                                              /v1/organizations

                                                              Marks multiple organizations as deleted.

                                                              Query parameters

                                                              ids

                                                              string

                                                              required

                                                              Comma-separated IDs that will be deleted

                                                              Response
                                                              200

                                                              success

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

                                                                Delete an organization

                                                                Copy link
                                                                Copy to clipboard
                                                                DELETE

                                                                /v1/organizations/{id}

                                                                Marks an organization as deleted.

                                                                Path parameters

                                                                id

                                                                integer

                                                                required

                                                                The ID of the Organization

                                                                Response
                                                                200

                                                                success

                                                                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

                                                                  success

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

                                                                    Subscribe to Pipedrive’s Developer Newsletter