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
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
    • [ ... ]
      • { ... }
        • { ... }

        Get all organizations (BETA)

        Copy link
        GET

        /v1/organizations/collection

        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.

        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

        OK

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

            Search organizations

            Copy link
            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. 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.

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