Persons

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.

Get all persons

Copy link

Returns all persons.

API v1
API v2

Endpoint is in beta

Request
GET

/api/v2/persons

Query parameters

filter_id

integer

If supplied, only persons matching the specified filter are returned

owner_id

integer

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

org_id

integer

If supplied, only persons linked to the specified organization are returned. If filter_id is provided, this is ignored.

updated_since

string

If set, only persons 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 persons 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. marketing_status and doi_status can only be included if the company has marketing app enabled.

Values

next_activity_id

last_activity_id

open_deals_count

related_open_deals_count

closed_deals_count

related_closed_deals_count

participant_open_deals_count

participant_closed_deals_count

email_messages_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

last_incoming_mail_time

last_outgoing_mail_time

marketing_status

doi_status

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 persons (BETA)

      Copy link

      Returns all persons. 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/persons/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 persons owned by the given user will be returned

      first_char

      string

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

      Response
      200

      OK

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

          Search persons

          Copy link

          Searches all persons by name, email, phone, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope. Found persons can be filtered by organization ID.

          API v1
          API v2

          Endpoint is in beta

          Request
          GET

          /api/v2/persons/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

          custom_fields

          email

          notes

          phone

          name

          exact_match

          boolean

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

          organization_id

          integer

          Will filter persons by the provided organization ID. The upper limit of found persons associated with the organization is 2000.

          include_fields

          string

          Supports including optional fields in the results which are not provided by default

          Values

          person.picture

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

              Copy link

              Returns the details of a person. Note that this also returns some additional fields which are not present when asking for all persons. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the key value of personFields.
              If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.

              API v1
              API v2

              Endpoint is in beta

              Request
              GET

              /api/v2/persons/{id}

              Path parameters

              id

              integer

              required

              The ID of the person

              Query parameters

              include_fields

              string

              Optional comma separated string array of additional fields to include. marketing_status and doi_status can only be included if the company has marketing app enabled.

              Values

              next_activity_id

              last_activity_id

              open_deals_count

              related_open_deals_count

              closed_deals_count

              related_closed_deals_count

              participant_open_deals_count

              participant_closed_deals_count

              email_messages_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

              last_incoming_mail_time

              last_outgoing_mail_time

              marketing_status

              doi_status

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

                Copy link

                Lists activities associated with a person.

                API v1
                Request
                GET

                /v1/persons/{id}/activities

                Path parameters

                id

                integer

                required

                The ID of the person

                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 person field values

                    Copy link

                    Lists updates about field values of a person.

                    API v1
                    Request
                    GET

                    /v1/persons/{id}/changelog

                    Path parameters

                    id

                    integer

                    required

                    The ID of the person

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

                        Copy link

                        Lists deals associated with a person.

                        API v1
                        Request
                        GET

                        /v1/persons/{id}/deals

                        Path parameters

                        id

                        integer

                        required

                        The ID of the person

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

                        Response
                        200

                        OK

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

                              List files attached to a person

                              Copy link

                              Lists files associated with a person.

                              API v1
                              Request
                              GET

                              /v1/persons/{id}/files

                              Path parameters

                              id

                              integer

                              required

                              The ID of the person

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

                                  Copy link

                                  Lists updates about a person.
                                  If a company uses the Campaigns product, then this endpoint's response will also include updates for the marketing_status field.

                                  API v1
                                  Request
                                  GET

                                  /v1/persons/{id}/flow

                                  Path parameters

                                  id

                                  integer

                                  required

                                  The ID of the person

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

                                  Response
                                  200

                                  OK

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

                                        List followers of a person

                                        Copy link

                                        Lists the followers of a person.

                                        API v1
                                        Request
                                        GET

                                        /v1/persons/{id}/followers

                                        Path parameters

                                        id

                                        integer

                                        required

                                        The ID of the person

                                        Response
                                        200

                                        OK

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

                                            List mail messages associated with a person

                                            Copy link

                                            Lists mail messages associated with a person.

                                            API v1
                                            Request
                                            GET

                                            /v1/persons/{id}/mailMessages

                                            Path parameters

                                            id

                                            integer

                                            required

                                            The ID of the person

                                            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 a person.

                                                API v1
                                                Request
                                                GET

                                                /v1/persons/{id}/permittedUsers

                                                Path parameters

                                                id

                                                integer

                                                required

                                                The ID of the person

                                                Response
                                                200

                                                OK

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

                                                  List products associated with a person

                                                  Copy link

                                                  Lists products associated with a person.

                                                  API v1
                                                  Request
                                                  GET

                                                  /v1/persons/{id}/products

                                                  Path parameters

                                                  id

                                                  integer

                                                  required

                                                  The ID of the person

                                                  Query parameters

                                                  start

                                                  integer

                                                  Pagination start

                                                  Default

                                                  0

                                                  limit

                                                  integer

                                                  Items shown per page

                                                  Response
                                                  200

                                                  OK

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

                                                      Add a person

                                                      Copy link

                                                      Adds a new person. 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 personFields and look for key values.
                                                      If a company uses the Campaigns product, then this endpoint will also accept and return the data.marketing_status field.

                                                      API v1
                                                      API v2

                                                      Endpoint is in beta

                                                      Request
                                                      POST

                                                      /api/v2/persons

                                                      Body parameters

                                                      application/json

                                                      name

                                                      string

                                                      The name of the person

                                                      owner_id

                                                      integer

                                                      The ID of the user who owns the person

                                                      org_id

                                                      integer

                                                      The ID of the organization linked to the person

                                                      add_time

                                                      string

                                                      The creation date and time of the person

                                                      update_time

                                                      string

                                                      The last updated date and time of the person

                                                      emails

                                                      array

                                                      The emails of the person

                                                      phones

                                                      array

                                                      The phones of the person

                                                      visible_to

                                                      integer

                                                      The visibility of the person

                                                      label_ids

                                                      array

                                                      The IDs of labels assigned to the person

                                                      Response
                                                      200

                                                      OK

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

                                                        Add a follower to a person

                                                        Copy link

                                                        Adds a follower to a person.

                                                        API v1
                                                        Request
                                                        POST

                                                        /v1/persons/{id}/followers

                                                        Path parameters

                                                        id

                                                        integer

                                                        required

                                                        The ID of the person

                                                        Body parameters

                                                        application/json

                                                        user_id

                                                        integer

                                                        required

                                                        The ID of the user

                                                        Response
                                                        200

                                                        OK

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

                                                          Add person picture

                                                          Copy link

                                                          Adds a picture to a person. If a picture is already set, the old picture will be replaced. Added image (or the cropping parameters supplied with the request) should have an equal width and height and should be at least 128 pixels. GIF, JPG and PNG are accepted. All added images will be resized to 128 and 512 pixel wide squares.

                                                          API v1
                                                          Request
                                                          POST

                                                          /v1/persons/{id}/picture

                                                          Path parameters

                                                          id

                                                          integer

                                                          required

                                                          The ID of the person

                                                          Body parameters

                                                          multipart/form-data

                                                          file

                                                          string

                                                          required

                                                          One image supplied in the multipart/form-data encoding

                                                          Format

                                                          binary

                                                          crop_x

                                                          integer

                                                          X coordinate to where start cropping form (in pixels)

                                                          crop_y

                                                          integer

                                                          Y coordinate to where start cropping form (in pixels)

                                                          crop_width

                                                          integer

                                                          The width of the cropping area (in pixels)

                                                          crop_height

                                                          integer

                                                          The height of the cropping area (in pixels)

                                                          Response
                                                          200

                                                          OK

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

                                                            Update a person

                                                            Copy link

                                                            Updates the properties of a person. For more information, see the tutorial for updating a person.
                                                            If a company uses the Campaigns product, then this endpoint will also accept and return the data.marketing_status field.

                                                            API v1
                                                            API v2

                                                            Endpoint is in beta

                                                            Request
                                                            PATCH

                                                            /api/v2/persons/{id}

                                                            Path parameters

                                                            id

                                                            integer

                                                            required

                                                            The ID of the person

                                                            Body parameters

                                                            application/json

                                                            name

                                                            string

                                                            The name of the person

                                                            owner_id

                                                            integer

                                                            The ID of the user who owns the person

                                                            org_id

                                                            integer

                                                            The ID of the organization linked to the person

                                                            add_time

                                                            string

                                                            The creation date and time of the person

                                                            update_time

                                                            string

                                                            The last updated date and time of the person

                                                            emails

                                                            array

                                                            The emails of the person

                                                            phones

                                                            array

                                                            The phones of the person

                                                            visible_to

                                                            integer

                                                            The visibility of the person

                                                            label_ids

                                                            array

                                                            The IDs of labels assigned to the person

                                                            Response
                                                            200

                                                            OK

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

                                                              Merge two persons

                                                              Copy link

                                                              Merges a person with another person. For more information, see the tutorial for merging two persons.

                                                              API v1
                                                              Request
                                                              PUT

                                                              /v1/persons/{id}/merge

                                                              Path parameters

                                                              id

                                                              integer

                                                              required

                                                              The ID of the person

                                                              Body parameters

                                                              application/json

                                                              merge_with_id

                                                              integer

                                                              required

                                                              The ID of the person that will not be overwritten. This person’s data will be prioritized in case of conflict with the other person.

                                                              Response
                                                              200

                                                              OK

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

                                                                Delete multiple persons in bulk

                                                                Copy link

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

                                                                API v1
                                                                Request
                                                                DELETE

                                                                /v1/persons

                                                                Query parameters

                                                                ids

                                                                string

                                                                required

                                                                The comma-separated IDs that will be deleted

                                                                Response
                                                                200

                                                                OK

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

                                                                  Delete a person

                                                                  Copy link

                                                                  Marks a person as deleted. After 30 days, the person will be permanently deleted.

                                                                  API v1
                                                                  API v2

                                                                  Endpoint is in beta

                                                                  Request
                                                                  DELETE

                                                                  /api/v2/persons/{id}

                                                                  Path parameters

                                                                  id

                                                                  integer

                                                                  required

                                                                  The ID of the person

                                                                  Response
                                                                  200

                                                                  OK

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

                                                                    Delete a follower from a person

                                                                    Copy link

                                                                    Deletes a follower from a person.

                                                                    API v1
                                                                    Request
                                                                    DELETE

                                                                    /v1/persons/{id}/followers/{follower_id}

                                                                    Path parameters

                                                                    id

                                                                    integer

                                                                    required

                                                                    The ID of the person

                                                                    follower_id

                                                                    integer

                                                                    required

                                                                    The ID of the follower

                                                                    Response
                                                                    200

                                                                    OK

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

                                                                      Delete person picture

                                                                      Copy link

                                                                      Deletes a person’s picture.

                                                                      API v1
                                                                      Request
                                                                      DELETE

                                                                      /v1/persons/{id}/picture

                                                                      Path parameters

                                                                      id

                                                                      integer

                                                                      required

                                                                      The ID of the person

                                                                      Response
                                                                      200

                                                                      OK

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

                                                                        Subscribe to Pipedrive’s Developer Newsletter