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
Copy to clipboard
GET

/v1/persons

Returns all persons.

Query parameters

user_id

integer

If supplied, only persons owned by the given user will be returned. However, filter_id takes precedence over user_id when both are supplied.

filter_id

integer

The ID of the filter to use

first_char

string

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

start

integer

Pagination start

Default

0

limit

integer

Items shown per page

sort

string

The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).

Response
200

OK

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

        Search persons

        Copy link
        Copy to clipboard
        GET

        /v1/persons/search

        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.

        Query parameters

        term

        string

        required

        The search term to look for. Minimum 2 characters (or 1 if using exact_match).

        fields

        string

        A comma-separated string array. The fields to perform the search from. Defaults to all of them.

        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.

        Values

        true

        false

        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

        start

        integer

        Pagination start. Note that the pagination is based on main results and does not include related items when using search_for_related_items parameter.

        Default

        0

        limit

        integer

        Items shown per page

        Response
        200

        OK

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

            Get details of a person

            Copy link
            Copy to clipboard
            GET

            /v1/persons/{id}

            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.

            Path parameters

            id

            integer

            required

            The ID of the person

            Response
            200

            OK

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

                  List activities associated with a person

                  Copy link
                  Copy to clipboard
                  GET

                  /v1/persons/{id}/activities

                  Lists activities associated with a person.

                  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 deals associated with a person

                      Copy link
                      Copy to clipboard
                      GET

                      /v1/persons/{id}/deals

                      Lists deals associated with a person.

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

                      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
                            Copy to clipboard
                            GET

                            /v1/persons/{id}/files

                            Lists files associated with a person.

                            Path parameters

                            id

                            integer

                            required

                            The ID of the person

                            Query parameters

                            start

                            integer

                            Pagination start

                            Default

                            0

                            limit

                            integer

                            Items shown per page

                            include_deleted_files

                            number

                            When enabled, the list of files will also include deleted files. Please note that trying to download these files will not work.

                            Values

                            0

                            1

                            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
                                Copy to clipboard
                                GET

                                /v1/persons/{id}/flow

                                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.

                                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
                                      Copy to clipboard
                                      GET

                                      /v1/persons/{id}/followers

                                      Lists the followers of a person.

                                      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
                                          Copy to clipboard
                                          GET

                                          /v1/persons/{id}/mailMessages

                                          Lists mail messages associated with a person.

                                          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
                                              Copy to clipboard
                                              GET

                                              /v1/persons/{id}/permittedUsers

                                              List users permitted to access a person.

                                              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
                                                Copy to clipboard
                                                GET

                                                /v1/persons/{id}/products

                                                Lists products associated with a person.

                                                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
                                                    Copy to clipboard
                                                    POST

                                                    /v1/persons

                                                    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.

                                                    Body parameters

                                                    application/json

                                                    name

                                                    string

                                                    required

                                                    The name of the person

                                                    owner_id

                                                    integer

                                                    The ID of the user who will be marked as the owner of this person. When omitted, the authorized user ID will be used.

                                                    org_id

                                                    integer

                                                    The ID of the organization this person will belong to

                                                    email

                                                    array

                                                    List of email data related to the person

                                                    primary_email

                                                    string

                                                    The primary email of the person

                                                    phone

                                                    array

                                                    List of phone data related to the person

                                                    visible_to

                                                    string

                                                    The visibility of the person. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.

                                                    Essential / Advanced plan

                                                    ValueDescription
                                                    1Owner & followers
                                                    3Entire company

                                                    Professional / Enterprise plan

                                                    ValueDescription
                                                    1Owner only
                                                    3Owner's visibility group
                                                    5Owner's visibility group and sub-groups
                                                    7Entire company

                                                    Values

                                                    1

                                                    3

                                                    5

                                                    7

                                                    marketing_status

                                                    If the person does not have a valid email address, then the marketing status is not set and no_consent is returned for the marketing_status value when the new person is created. If the change is forbidden, the status will remain unchanged for every call that tries to modify the marketing status. Please be aware that it is only allowed once to change the marketing status from an old status to a new one.

                                                    ValueDescription
                                                    no_consentThe customer has not given consent to receive any marketing communications
                                                    unsubscribedThe customers have unsubscribed from ALL marketing communications
                                                    subscribedThe customers are subscribed and are counted towards marketing caps
                                                    archivedThe customers with subscribed status can be moved to archived to save consent, but they are not paid for

                                                    Values

                                                    no_consent

                                                    unsubscribed

                                                    subscribed

                                                    archived

                                                    add_time

                                                    string

                                                    The optional creation date & time of the person in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

                                                    Response
                                                    201

                                                    Created

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

                                                        Add a follower to a person

                                                        Copy link
                                                        Copy to clipboard
                                                        POST

                                                        /v1/persons/{id}/followers

                                                        Adds a follower to a person.

                                                        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
                                                          Copy to clipboard
                                                          POST

                                                          /v1/persons/{id}/picture

                                                          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.

                                                          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
                                                            Copy to clipboard
                                                            PUT

                                                            /v1/persons/{id}

                                                            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.

                                                            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 will be marked as the owner of this person. When omitted, the authorized user ID will be used.

                                                            org_id

                                                            integer

                                                            The ID of the organization this person will belong to

                                                            email

                                                            array

                                                            List of email data related to the person

                                                            primary_email

                                                            string

                                                            The primary email of the person

                                                            phone

                                                            array

                                                            List of phone data related to the person

                                                            visible_to

                                                            string

                                                            The visibility of the person. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.

                                                            Essential / Advanced plan

                                                            ValueDescription
                                                            1Owner & followers
                                                            3Entire company

                                                            Professional / Enterprise plan

                                                            ValueDescription
                                                            1Owner only
                                                            3Owner's visibility group
                                                            5Owner's visibility group and sub-groups
                                                            7Entire company

                                                            Values

                                                            1

                                                            3

                                                            5

                                                            7

                                                            marketing_status

                                                            If the person does not have a valid email address, then the marketing status is not set and no_consent is returned for the marketing_status value when the new person is created. If the change is forbidden, the status will remain unchanged for every call that tries to modify the marketing status. Please be aware that it is only allowed once to change the marketing status from an old status to a new one.

                                                            ValueDescription
                                                            no_consentThe customer has not given consent to receive any marketing communications
                                                            unsubscribedThe customers have unsubscribed from ALL marketing communications
                                                            subscribedThe customers are subscribed and are counted towards marketing caps
                                                            archivedThe customers with subscribed status can be moved to archived to save consent, but they are not paid for

                                                            Values

                                                            no_consent

                                                            unsubscribed

                                                            subscribed

                                                            archived

                                                            add_time

                                                            string

                                                            The optional creation date & time of the person in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

                                                            Response
                                                            200

                                                            OK

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

                                                                Merge two persons

                                                                Copy link
                                                                Copy to clipboard
                                                                PUT

                                                                /v1/persons/{id}/merge

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

                                                                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
                                                                  Copy to clipboard
                                                                  DELETE

                                                                  /v1/persons

                                                                  Marks multiple persons as deleted.

                                                                  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
                                                                    Copy to clipboard
                                                                    DELETE

                                                                    /v1/persons/{id}

                                                                    Marks a person as deleted.

                                                                    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
                                                                      Copy to clipboard
                                                                      DELETE

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

                                                                      Deletes a follower from a person.

                                                                      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
                                                                        Copy to clipboard
                                                                        DELETE

                                                                        /v1/persons/{id}/picture

                                                                        Deletes a person’s 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