Pipedrive Organizations API

openapi: 3.0.1
info:
  title: Pipedrive API v1 Activities Organizations API
  version: 1.0.0
  description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.

    '
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: Organizations
  description: '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.

    '
paths:
  /organizations/{id}/changelog:
    get:
      summary: List updates about organization field values
      description: Lists updates about field values of an organization.
      x-token-cost: 20
      operationId: getOrganizationChangelog
      tags:
      - Organizations
      security:
      - api_key: []
      - oauth2:
        - recents:read
      parameters:
      - in: path
        name: id
        description: The ID of the organization
        required: true
        schema:
          type: integer
      - in: query
        name: cursor
        description: For pagination, the marker (an opaque string value) representing the first item on the next page
        schema:
          type: string
      - in: query
        name: limit
        description: Items shown per page
        schema:
          type: integer
      responses:
        '200':
          description: Get changelog of an organization
          content:
            application/json:
              schema:
                title: GetChangelogResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        properties:
                          field_key:
                            type: string
                            description: The key of the field that was changed
                          old_value:
                            type: string
                            nullable: true
                            description: The value of the field before the change
                          new_value:
                            type: string
                            nullable: true
                            description: The value of the field after the change
                          actor_user_id:
                            type: integer
                            description: The ID of the user who made the change
                          time:
                            type: string
                            description: The date and time of the change
                          change_source:
                            type: string
                            nullable: true
                            description: The source of change, for example 'app', 'mobile', 'api', etc.
                          change_source_user_agent:
                            type: string
                            nullable: true
                            description: The user agent from which the change was made
                          is_bulk_update_flag:
                            type: boolean
                            description: Whether the change was made as part of a bulk update
                    additional_data:
                      description: The additional data of the list
                      type: object
                      properties:
                        next_cursor:
                          type: string
                          description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned.
              example:
                success: true
                data:
                - field_key: name
                  old_value: Org 10
                  new_value: Org 11
                  actor_user_id: 26
                  time: '2024-02-12 09:14:35'
                  change_source: app
                  change_source_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36
                  is_bulk_update_flag: false
                - field_key: 51c27e4a19c3bedd91162a9d446707c1f95174ea
                  old_value: '0'
                  new_value: '20'
                  actor_user_id: 26
                  time: '2024-02-12 09:10:12'
                  change_source: app
                  change_source_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36
                  is_bulk_update_flag: false
                additional_data:
                  next_cursor: aWQ6NTQ0
  /organizations/{id}/files:
    get:
      summary: List files attached to an organization
      description: Lists files associated with an organization.
      x-token-cost: 20
      operationId: getOrganizationFiles
      tags:
      - Organizations
      security:
      - api_key: []
      - oauth2:
        - contacts:read
        - contacts:full
      parameters:
      - in: path
        name: id
        description: The ID of the organization
        required: true
        schema:
          type: integer
      - in: query
        name: start
        description: Pagination start
        schema:
          type: integer
          default: 0
      - in: query
        name: limit
        description: Items shown per page. Please note that a maximum value of 100 is allowed.
        schema:
          type: integer
          maximum: 100
      - in: query
        name: sort
        schema:
          type: string
        description: 'Supported fields: `id`, `update_time`'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: GetAssociatedFilesResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        description: The file data
                        properties:
                          id:
                            type: integer
                            description: The ID of the file
                          user_id:
                            type: integer
                            description: The ID of the user to associate the file with
                          deal_id:
                            type: integer
                            description: The ID of the deal to associate the file with
                          person_id:
                            type: integer
                            description: The ID of the person to associate the file with
                          org_id:
                            type: integer
                            description: The ID of the organization to associate the file with
                          product_id:
                            type: integer
                            description: The ID of the product to associate the file with
                          activity_id:
                            type: integer
                            description: The ID of the activity to associate the file with
                          lead_id:
                            type: string
                            description: The ID of the lead to associate the file with
                            format: uuid
                          add_time:
                            type: string
                            description: 'The date and time when the file was added/created. Format: YYYY-MM-DD HH:MM:SS'
                          update_time:
                            type: string
                            description: 'The last updated date and time of the file. Format: YYYY-MM-DD HH:MM:SS'
                          file_name:
                            type: string
                            description: The original name of the file
                          file_size:
                            type: integer
                            description: The size of the file
                          active_flag:
                            type: boolean
                            description: Whether the user is active or not. false = Not activated, true = Activated
                          inline_flag:
                            type: boolean
                            description: Whether the file was uploaded as inline or not
                          remote_location:
                            type: string
                            description: The location type to send the file to. Only googledrive is supported at the moment.
                          remote_id:
                            type: string
                            description: The ID of the remote item
                          cid:
                            type: string
                            description: The ID of the inline attachment
                          s3_bucket:
                            type: string
                            description: The location of the cloud storage
                          mail_message_id:
                            type: string
                            description: The ID of the mail message to associate the file with
                          mail_template_id:
                            type: string
                            description: The ID of the mail template to associate the file with
                          deal_name:
                            type: string
                            description: The name of the deal associated with the dile
                          person_name:
                            type: string
                            description: The name of the person associated with the file
                          org_name:
                            type: string
                            description: The name of the organization associated with the file
                          product_name:
                            type: string
                            description: The name of the product associated with the file
                          lead_name:
                            type: string
                            description: The name of the lead associated with the file
                          url:
                            type: string
                            description: The URL of the download file
                          name:
                            type: string
                            description: The visible name of the file
                          description:
                            type: string
                            description: The description of the file
                      description: The array of files
                    additional_data:
                      description: The additional data of the list
                      type: object
                      properties:
                        start:
                          type: integer
                          description: Pagination start
                        limit:
                          type: integer
                          description: Items shown per page
                        more_items_in_collection:
                          type: boolean
                          description: If there are more list items in the collection than displayed or not
              example:
                success: true
                data:
                - id: 1
                  user_id: 8877
                  deal_id: 1
                  person_id: 1
                  org_id: 1480
                  product_id: 1
                  activity_id: 1
                  lead_id: adf21080-0e10-11eb-879b-05d71fb426ec
                  log_id: null
                  add_time: '2020-09-16 11:19:36'
                  update_time: '2020-09-16 11:19:36'
                  file_name: 95781006_794143070992462_4330873630616453120_n_60817458877506f9eb74d03e5ef9ba061915b797998.jpg
                  file_type: img
                  file_size: 95116
                  active_flag: true
                  inline_flag: false
                  remote_location: s3
                  remote_id: 95781006_794143070992462_4330873630616453120_n.jpg
                  cid: ''
                  s3_bucket: ''
                  mail_message_id: ''
                  mail_template_id: ''
                  deal_name: nice deal
                  person_name: ''
                  people_name: ''
                  org_name: Pipedrive Inc.
                  product_name: ''
                  lead_name: nice lead
                  url: https://app.pipedrive.com/api/v1/files/304/download
                  name: 95781006_794143070992462_4330873630616453120_n.jpg
                  description: ''
                additional_data:
                  pagination:
                    start: 0
                    limit: 100
                    more_items_in_collection: true
  /organizations/{id}/flow:
    get:
      summary: List updates about an organization
      description: Lists updates about an organization.
      x-token-cost: 40
      operationId: getOrganizationUpdates
      tags:
      - Organizations
      security:
      - api_key: []
      - oauth2:
        - recents:read
      parameters:
      - in: path
        name: id
        description: The ID of the organization
        required: true
        schema:
          type: integer
      - in: query
        name: start
        description: Pagination start
        schema:
          type: integer
          default: 0
      - in: query
        name: limit
        description: Items shown per page
        schema:
          type: integer
      - in: query
        name: all_changes
        description: Whether to show custom field updates or not. 1 = Include custom field changes. If omitted, returns changes without custom field updates.
        schema:
          type: string
      - in: query
        name: items
        description: 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).
        schema:
          type: string
      responses:
        '200':
          description: Get the organization updates
          content:
            application/json:
              schema:
                title: GetAssociatedOrganizationUpdatesResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        properties:
                          object:
                            type: string
                            description: The type of the person update. (Possible object types - organizationChange, dealChange, file, activity)
                          timestamp:
                            type: string
                            description: The creation date and time of the update
                          data:
                            type: object
                            description: The data related to the update
                    additional_data:
                      description: The additional data of the list
                      type: object
                      properties:
                        start:
                          type: integer
                          description: Pagination start
                        limit:
                          type: integer
                          description: Items shown per page
                        more_items_in_collection:
                          type: boolean
                          description: If there are more list items in the collection than displayed or not
                    related_objects:
                      type: object
                      properties:
                        organization:
                          type: object
                          title: RelatedOrganizationData
                          properties:
                            ORGANIZATION_ID:
                              type: object
                              title: OrganizationDataWithId
                              description: The ID of the organization associated with the item
                              allOf:
                              - type: object
                                properties:
                                  id:
                                    type: integer
                                    description: The ID of the organization associated with the item
                              - type: object
                                properties:
                                  name:
                                    type: string
                                    description: The name of the organization associated with the item
                                  people_count:
                                    type: integer
                                    description: The number of people connected with the organization that is associated with the item
                                  owner_id:
                                    type: integer
                                    description: The ID of the owner of the organization that is associated with the item
                                  address:
                                    type: string
                                    nullable: true
                                    description: The address of the organization
                                  cc_email:
                                    type: string
                                    nullable: true
                                    description: The BCC email of the organization associated with the item
                        user:
                          type: object
                          properties:
                            USER_ID:
                              type: object
                              title: userDataWithId
                              allOf:
                              - properties:
                                  id:
                                    type: integer
                                    description: The ID of the user
                                  name:
                                    type: string
                                    description: The name of the user
                                  email:
                                    type: string
                                    description: The email of the user
                                  has_pic:
                                    type: integer
                                    description: Whether the user has picture or not. 0 = No picture, 1 = Has picture.
                                  pic_hash:
                                    type: string
                                    nullable: true
                                    description: The user picture hash
                                  active_flag:
                                    type: boolean
                                    description: Whether the user is active or not
                              - type: object
                                description: The ID of the user
              example:
                success: true
                data:
                - object: organizationChange
                  timestamp: '2020-09-15 11:55:14'
                  data:
                    id: 3694
                    item_id: 1480
                    user_id: 9271535
                    field_key: owner_id
                    old_value: 9271535
                    new_value: 8877
                    is_bulk_update_flag: null
                    log_time: '2020-09-15 11:55:14'
                    change_source: app
                    change_source_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML like Gecko) Chrome/84.0.4147.135 Safari/537.36
                    additional_data:
                      new_value_formatted: Will Smith
                      old_value_formatted: Robert Smith
                - object: activity
                  timestamp: '2020-08-07 08:15:00'
                  data:
                    id: 8
                    company_id: 22122
                    user_id: 1234
                    done: false
                    type: deadline
                    reference_type: scheduler-service
                    reference_id: 7
                    conference_meeting_client: 871b8bc88d3a1202
                    conference_meeting_url: https://pipedrive.zoom.us/link
                    conference_meeting_id: '17058746701'
                    due_date: '2020-06-09'
                    due_time: '10:00'
                    duration: 01:00
                    busy_flag: true
                    add_time: '2020-06-08 12:37:56'
                    marked_as_done_time: '2020-08-08 08:08:38'
                    last_notification_time: '2020-08-08 12:37:56'
                    last_notification_user_id: 7655
                    notification_language_id: 1
                    subject: Deadline
                    public_description: This is a description
                    calendar_sync_include_context: ''
                    location: Mustamäe tee 3, Tallinn, Estonia
                    org_id: 5
                    person_id: 1101
                    deal_id: 300
                    lead_id: 46c3b0e1-db35-59ca-1828-4817378dff71
                    project_id: null
                    active_flag: true
                    update_time: '2020-08-08 12:37:56'
                    update_user_id: 5596
                    gcal_event_id: ''
                    google_calendar_id: ''
                    google_calendar_etag: ''
                    source_timezone: ''
                    rec_rule: RRULE:FREQ=WEEKLY;BYDAY=WE
                    rec_rule_extension: ''
                    rec_master_activity_id: 1
                    series: []
                    note: A note for the activity
                    created_by_user_id: 1234
                    location_subpremise: ''
                    location_street_number: '3'
                    location_route: Mustamäe tee
                    location_sublocality: Kristiine
                    location_locality: Tallinn
                    location_admin_area_level_1: Harju maakond
                    location_admin_area_level_2: ''
                    location_country: Estonia
                    location_postal_code: '10616'
                    location_formatted_address: Mustamäe tee 3, 10616 Tallinn, Estonia
                    attendees:
                    - email_address: attendee@pipedrivemail.com
                      is_organizer: 0
                      name: Attendee
                      person_id: 25312
                      status: noreply
                      user_id: null
                    participants:
                    - person_id: 17985
                      primary_flag: false
                    - person_id: 1101
                      primary_flag: true
                    org_name: Organization
                    person_name: Person
                    deal_title: Deal
                    owner_name: Creator
                    person_dropbox_bcc: company@pipedrivemail.com
                    deal_dropbox_bcc: company+deal300@pipedrivemail.com
                    assigned_to_user_id: 1235
                    file:
                      id: 376892,
                      clean_name: Audio 10:55:07.m4a
                      url: https://pipedrive-files.s3-eu-west-1.amazonaws.com/Audio-recording.m4a
                - object: file
                  timestamp: '2020-08-10 11:52:26'
                  data:
                    id: 1
                    user_id: 8877
                    deal_id: 1
                    person_id: 1
                    org_id: 1480
                    product_id: 1
                    activity_id: 1
                    lead_id: adf21080-0e10-11eb-879b-05d71fb426ec
                    log_id: null
                    add_time: '2020-09-16 11:19:36'
                    update_time: '2020-09-16 11:19:36'
                    file_name: 95781006_794143070992462_4330873630616453120_n_60817458877506f9eb74d03e5ef9ba061915b797998.jpg
                    file_type: img
                    file_size: 95116
                    active_flag: true
                    inline_flag: false
                    remote_location: s3
                    remote_id: 95781006_794143070992462_4330873630616453120_n.jpg
                    cid: ''
                    s3_bucket: ''
                    mail_message_id: ''
                    mail_template_id: ''
                    deal_name: nice deal
                    person_name: ''
                    people_name: ''
                    org_name: Pipedrive Inc.
                    product_name: ''
                    lead_name: nice lead
                    url: https://app.pipedrive.com/api/v1/files/304/download
                    name: 95781006_794143070992462_4330873630616453120_n.jpg
                    description: ''
                additional_data:
                  pagination:
                    start: 0
                    limit: 100
                    more_items_in_collection: true
                related_objects:
                  allOf:
                  - user:
                      '123':
                        id: 123
                        name: Jane Doe
                        email: jane@pipedrive.com
                        has_pic: 1
                        pic_hash: 2611ace8ac6a3afe2f69ed56f9e08c6b
                        active_flag: true
                  - organization:
                      '1':
                        id: 1
                        name: Org Name
                        people_count: 1
                        owner_id: 123
                        address: Mustamäe tee 3a, 10615 Tallinn
                        active_flag: true
                        cc_email: org@pipedrivemail.com
  /organizations/{id}/followers:
    get:
      summary: List followers of an organization
      description: Lists the followers of an organization.
      x-token-cost: 20
      operationId: getOrganizationFollowers
      tags:
      - Organizations
      security:
      - api_key: []
      - oauth2:
        - contacts:read
        - contacts:full
      parameters:
      - in: path
        name: id
        description: The ID of the organization
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: GetAssociatedFollowersResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the request was successful or not
                  data:
                    type: array
                    description: The array of followers
                    items:
                      allOf:
                      - type: object
                        properties:
                          org_id:
                            type: integer
                            description: The ID of the organization
                      - type: object
                        properties:
                          user_id:
                            type: integer
                            description: The user ID of the follower related to the item
                          id:
                            type: integer
                            description: The ID of the follower
                          add_time:
                            type: string
                            format: date-time
                            description: The date and time of adding the follower to the item
                  additional_data:
                    type: object
                    properties:
                      pagination:
                        description: Pagination details of the list
                        type: object
                        properties:
                          start:
                            type: integer
                            description: Pagination start
                          limit:
                            type: integer
                            description: Items shown per page
                          more_items_in_collection:
                            type: boolean
                            description: Whether there are more list items in the collection than displayed
                          next_start:
                            type: integer
                            description: Next pagination start
              example:
                success: true
                data:
                - user_id: 100
                  id: 123
                  org_id: 77
                  add_time: '2020-09-08 08:17:52'
                additional_data:
                  pagination:
                    start: 0
                    limit: 100
                    more_items_in_collection: false
                    next_start: 100
    post:
      summary: Add a follower to an organization
      description: Adds a follower to an organization.
      x-token-cost: 10
      operationId: addOrganizationFollower
      tags:
      - Organizations
      security:
      - api_key: []
      - oauth2:
        - contacts:full
      parameters:
      - in: path
        name: id
        description: The ID of the organization
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              title: addOrganizationFollowerRequest
              type: object
              required:
              - user_id
              properties:
                user_id:
                  type: integer
                  description: The ID of the user
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: AddOrganizationFollowerResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the request was successful or not
                  data:
                    allOf:
                    - type: object
                      properties:
                        org_id:
                          type: integer
                          description: The ID of the organization
                    - type: object
                      properties:
                        user_id:
                          type: integer
                          description: The user ID of the follower related to the item
                        id:
                          type: integer
                          description: The ID of the follower
                        add_time:
                          type: string
                          format: date-time
                          description: The date and time of adding the follower to the item
              example:
                success: true
                data:
      

# --- truncated at 32 KB (107 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-organizations-api-openapi.yml