Pipedrive Persons API

openapi: 3.0.1
info:
  title: Pipedrive API v1 Activities Persons 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: Persons
  description: 'Persons are your contacts, the customers you are doing deals with. Each person can belong to an organization. Persons should not be confused with users.

    '
paths:
  /persons/{id}/changelog:
    get:
      summary: List updates about person field values
      description: Lists updates about field values of a person.
      x-token-cost: 20
      operationId: getPersonChangelog
      tags:
      - Persons
      security:
      - api_key: []
      - oauth2:
        - recents:read
      parameters:
      - in: path
        name: id
        description: The ID of the person
        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 a person
          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: 51c27e4a19c3bedd91162a9d446707c1f95174ea
                  old_value: null
                  new_value: '200'
                  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: email
                  old_value: john.doe@pipedrive.com
                  new_value: jane.doe@pipedrive.com
                  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
  /persons/{id}/files:
    get:
      summary: List files attached to a person
      description: Lists files associated with a person.
      x-token-cost: 20
      operationId: getPersonFiles
      tags:
      - Persons
      security:
      - api_key: []
      - oauth2:
        - contacts:read
        - contacts:full
      parameters:
      - in: path
        name: id
        description: The ID of the person
        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
  /persons/{id}/flow:
    get:
      summary: List updates about a person
      description: Lists updates about a person.<br>If a company uses the [Campaigns product](https://pipedrive.readme.io/docs/campaigns-in-pipedrive-api), then this endpoint's response will also include updates for the `marketing_status` field.
      x-token-cost: 40
      operationId: getPersonUpdates
      tags:
      - Persons
      security:
      - api_key: []
      - oauth2:
        - recents:read
      parameters:
      - in: path
        name: id
        description: The ID of the person
        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 - call, activity, plannedActivity, change, note, deal, file, dealChange, personChange, organizationChange, follower, dealFollower, personFollower, organizationFollower, participant, comment, mailMessage, mailMessageWithAttachment, invoice, document, marketing_campaign_stat, marketing_status_change).
        schema:
          type: string
      responses:
        '200':
          description: Get the person updates
          content:
            application/json:
              schema:
                title: GetAssociatedPersonUpdatesResponse
                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 - personChange, note, activity, file)
                          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:
                        deal:
                          type: object
                          title: RelatedDealData
                          properties:
                            DEAL_ID:
                              type: object
                              description: The ID of the deal which is associated with the item
                              properties:
                                id:
                                  type: integer
                                  description: The ID of the deal associated with the item
                                title:
                                  type: string
                                  description: The title of the deal associated with the item
                                status:
                                  type: string
                                  description: The status of the deal associated with the item
                                value:
                                  type: number
                                  description: The value of the deal that is associated with the item
                                currency:
                                  type: string
                                  description: The currency of the deal value
                                stage_id:
                                  type: integer
                                  description: The ID of the stage the deal is currently at
                                pipeline_id:
                                  type: integer
                                  description: The ID of the pipeline the deal is in
                        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
                        person:
                          type: object
                          properties:
                            PERSON_ID:
                              type: object
                              description: The ID of the person associated with the item
                              title: PersonDataWithActiveFlag
                              allOf:
                              - type: object
                                properties:
                                  active_flag:
                                    type: boolean
                                    description: Whether the associated person is active or not
                              - type: object
                                properties:
                                  id:
                                    type: integer
                                    description: The ID of the person associated with the item
                                  name:
                                    type: string
                                    description: The name of the person associated with the item
                                  email:
                                    type: array
                                    description: The emails of the person associated with the item
                                    items:
                                      type: object
                                      properties:
                                        label:
                                          type: string
                                          description: The type of the email
                                        value:
                                          type: string
                                          description: The email of the associated person
                                        primary:
                                          type: boolean
                                          description: Whether this is the primary email or not
                                  phone:
                                    type: array
                                    description: The phone numbers of the person associated with the item
                                    items:
                                      type: object
                                      title: PhoneData
                                      properties:
                                        label:
                                          type: string
                                          description: The type of the phone number
                                        value:
                                          type: string
                                          description: The phone number of the person associated with the item
                                        primary:
                                          type: boolean
                                          description: Whether this is the primary phone number or not
                                  owner_id:
                                    type: integer
                                    description: The ID of the owner of the person that is associated with the item
              example:
                success: true
                data:
                - object: personChange
                  timestamp: '2020-08-03 11:25:21'
                  data:
                    id: 11158
                    item_id: 3512
                    user_id: 8877
                    field_key: org_id
                    old_value: null
                    new_value: 1482
                    is_bulk_update_flag: null
                    log_time: '2020-08-03 11:25:21'
                    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.89 Safari/537.36
                    additional_data:
                      new_value_formatted: Umbrella Corp.
                - 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
                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
                  - person:
                      '1101':
                        active_flag: true
                        id: 1101
                        name: Person
                        email:
                        - label: work
                          value: person@pipedrive.com
                          primary: true
                        phone:
                        - label: work
                          value: '3421787767'
                          primary: true
                        owner_id: 8877
                  - 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
  /persons/{id}/followers:
    get:
      summary: List followers of a person
      description: Lists the followers of a person.
      x-token-cost: 20
      operationId: getPersonFollowers
      tags:
      - Persons
      security:
      - api_key: []
      - oauth2:
        - contacts:read
        - contacts:full
      parameters:
      - in: path
        name: id
        description: The ID of the person
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: GetListFollowersResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: array
                      description: The list of followers
                      items:
                        type: object
                        properties:
                          user_id:
                          

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