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

Returns all organizations.

API v1
API v2

Endpoint is in beta

Request
GET

/api/v2/organizations

Query parameters

filter_id

integer

If supplied, only organizations matching the specified filter are returned

owner_id

integer

If supplied, only organization owned by the specified user are returned. If filter_id is provided, this is ignored.

updated_since

string

If set, only organizations with an update_time later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.

updated_until

string

If set, only organizations with an update_time earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.

sort_by

string

The field to sort by. Supported fields: id, update_time, add_time.

Default

id

Values

id

update_time

add_time

sort_direction

string

The sorting direction. Supported values: asc, desc.

Default

asc

Values

asc

desc

include_fields

string

Optional comma separated string array of additional fields to include

Values

next_activity_id

last_activity_id

open_deals_count

related_open_deals_count

closed_deals_count

related_closed_deals_count

email_messages_count

people_count

activities_count

done_activities_count

undone_activities_count

files_count

notes_count

followers_count

won_deals_count

related_won_deals_count

lost_deals_count

related_lost_deals_count

custom_fields

string

Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.
A maximum of 15 keys is allowed.

limit

integer

For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.

cursor

string

For pagination, the marker (an opaque string value) representing the first item on the next page

Response
200

OK

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

      Get all organizations (BETA)

      Copy link

      Returns all organizations. This is a cursor-paginated endpoint that is currently in BETA. For more information, please refer to our documentation on pagination. Please note that only global admins (those with global permissions) can access these endpoints. Users with regular permissions will receive a 403 response. Read more about global permissions here.

      API v1
      Request
      GET

      /v1/organizations/collection

      Query parameters

      cursor

      string

      For pagination, the marker (an opaque string value) representing the first item on the next page

      limit

      integer

      For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.

      since

      string

      The time boundary that points to the start of the range of data. Datetime in ISO 8601 format. E.g. 2022-11-01 08:55:59. Operates on the update_time field.

      until

      string

      The time boundary that points to the end of the range of data. Datetime in ISO 8601 format. E.g. 2022-11-01 08:55:59. Operates on the update_time field.

      owner_id

      integer

      If supplied, only organizations owned by the given user will be returned

      first_char

      string

      If supplied, only organizations whose name starts with the specified letter will be returned (case-insensitive)

      Response
      200

      OK

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

          Search organizations

          Copy link

          Searches all organizations by name, address, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.

          API v1
          API v2

          Endpoint is in beta

          Request
          GET

          /api/v2/organizations/search

          Query parameters

          term

          string

          required

          The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.

          fields

          string

          A comma-separated string array. The fields to perform the search from. Defaults to all of them. Only the following custom field types are searchable: address, varchar, text, varchar_auto, double, monetary and phone. Read more about searching by custom fields here.

          Values

          address

          custom_fields

          notes

          name

          exact_match

          boolean

          When enabled, only full exact matches against the given term are returned. It is not case sensitive.

          limit

          integer

          For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.

          cursor

          string

          For pagination, the marker (an opaque string value) representing the first item on the next page

          Response
          200

          OK

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

              Get details of an organization

              Copy link

              Returns the details of an organization. Note that this also returns some additional fields which are not present when asking for all organizations. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the key value of organizationFields.

              API v1
              API v2

              Endpoint is in beta

              Request
              GET

              /api/v2/organizations/{id}

              Path parameters

              id

              integer

              required

              The ID of the organization

              Query parameters

              include_fields

              string

              Optional comma separated string array of additional fields to include

              Values

              next_activity_id

              last_activity_id

              open_deals_count

              related_open_deals_count

              closed_deals_count

              related_closed_deals_count

              email_messages_count

              people_count

              activities_count

              done_activities_count

              undone_activities_count

              files_count

              notes_count

              followers_count

              won_deals_count

              related_won_deals_count

              lost_deals_count

              related_lost_deals_count

              custom_fields

              string

              Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.
              A maximum of 15 keys is allowed.

              Response
              200

              OK

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

                List activities associated with an organization

                Copy link

                Lists activities associated with an organization.

                API v1
                Request
                GET

                /v1/organizations/{id}/activities

                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 updates about organization field values

                    Copy link

                    Lists updates about field values of an organization.

                    API v1
                    Request
                    GET

                    /v1/organizations/{id}/changelog

                    Path parameters

                    id

                    integer

                    required

                    The ID of the organization

                    Query parameters

                    cursor

                    string

                    For pagination, the marker (an opaque string value) representing the first item on the next page

                    limit

                    integer

                    Items shown per page

                    Response
                    200

                    OK

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

                        List deals associated with an organization

                        Copy link

                        Lists deals associated with an organization.

                        API v1
                        Request
                        GET

                        /v1/organizations/{id}/deals

                        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

                              Lists files associated with an organization.

                              API v1
                              Request
                              GET

                              /v1/organizations/{id}/files

                              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

                                  Lists updates about an organization.

                                  API v1
                                  Request
                                  GET

                                  /v1/organizations/{id}/flow

                                  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

                                        Lists the followers of an organization.

                                        API v1
                                        Request
                                        GET

                                        /v1/organizations/{id}/followers

                                        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

                                            Lists mail messages associated with an organization.

                                            API v1
                                            Request
                                            GET

                                            /v1/organizations/{id}/mailMessages

                                            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

                                                List users permitted to access an organization.

                                                API v1
                                                Request
                                                GET

                                                /v1/organizations/{id}/permittedUsers

                                                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

                                                  Lists persons associated with an organization.
                                                  If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.

                                                  API v1
                                                  Request
                                                  GET

                                                  /v1/organizations/{id}/persons

                                                  Path parameters

                                                  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

                                                        Adds a new organization. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys. To determine which custom fields exists, fetch the organizationFields and look for key values. For more information, see the tutorial for adding an organization.

                                                        API v1
                                                        API v2

                                                        Endpoint is in beta

                                                        Request
                                                        POST

                                                        /api/v2/organizations

                                                        Body parameters

                                                        application/json

                                                        name

                                                        string

                                                        The name of the organization

                                                        owner_id

                                                        integer

                                                        The ID of the user who owns the organization

                                                        add_time

                                                        string

                                                        The creation date and time of the organization

                                                        update_time

                                                        string

                                                        The last updated date and time of the organization

                                                        visible_to

                                                        integer

                                                        The visibility of the organization

                                                        label_ids

                                                        array

                                                        The IDs of labels assigned to the organization

                                                        Response
                                                        200

                                                        OK

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

                                                          Add a follower to an organization

                                                          Copy link

                                                          Adds a follower to an organization.

                                                          API v1
                                                          Request
                                                          POST

                                                          /v1/organizations/{id}/followers

                                                          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

                                                            Updates the properties of an organization.

                                                            API v1
                                                            API v2

                                                            Endpoint is in beta

                                                            Request
                                                            PATCH

                                                            /api/v2/organizations/{id}

                                                            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 owns the organization

                                                            add_time

                                                            string

                                                            The creation date and time of the organization

                                                            update_time

                                                            string

                                                            The last updated date and time of the organization

                                                            visible_to

                                                            integer

                                                            The visibility of the organization

                                                            label_ids

                                                            array

                                                            The IDs of labels assigned to the organization

                                                            Response
                                                            200

                                                            OK

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

                                                              Merge two organizations

                                                              Copy link

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

                                                              API v1
                                                              Request
                                                              PUT

                                                              /v1/organizations/{id}/merge

                                                              Path parameters

                                                              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

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

                                                                API v1
                                                                Request
                                                                DELETE

                                                                /v1/organizations

                                                                Query parameters

                                                                ids

                                                                string

                                                                required

                                                                The comma-separated IDs that will be deleted

                                                                Response
                                                                200

                                                                OK

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

                                                                  Delete an organization

                                                                  Copy link

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

                                                                  API v1
                                                                  API v2

                                                                  Endpoint is in beta

                                                                  Request
                                                                  DELETE

                                                                  /api/v2/organizations/{id}

                                                                  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

                                                                    Deletes a follower from an organization. You can retrieve the follower_id from the List followers of an organization endpoint.

                                                                    API v1
                                                                    Request
                                                                    DELETE

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

                                                                    Path parameters

                                                                    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