Leads

Leads are potential deals stored in Leads Inbox before they are archived or converted to a deal. Each lead needs to be named (using the title field) and be linked to a person or an organization. In addition to that, a lead can contain most of the fields a deal can (such as value or expected_close_date).

Get all leads

Copy link

Returns multiple not archived leads. Leads are sorted by the time they were created, from oldest to newest. Pagination can be controlled using limit and start query parameters. If a lead contains custom fields, the fields' values will be included in the response in the same format as with the Deals endpoints. If a custom field's value hasn't been set for the lead, it won't appear in the response. Please note that leads do not have a separate set of custom fields, instead they inherit the custom fields' structure from deals.

API v1
Cost

20

Request
GET

/v1/leads

Query parameters

limit

integer

For pagination, the limit of entries to be returned. If not provided, 100 items will be returned.

start

integer

For pagination, the position that represents the first result for the page

owner_id

integer

If supplied, only leads matching the given user will be returned. However, filter_id takes precedence over owner_id when supplied.

person_id

integer

If supplied, only leads matching the given person will be returned. However, filter_id takes precedence over person_id when supplied.

organization_id

integer

If supplied, only leads matching the given organization will be returned. However, filter_id takes precedence over organization_id when supplied.

filter_id

integer

The ID of the filter to use

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

Values

id

title

owner_id

creator_id

was_seen

expected_close_date

next_activity_id

add_time

update_time

Response
200

OK

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

    Get all archived leads

    Copy link

    Returns multiple archived leads. Leads are sorted by the time they were created, from oldest to newest. Pagination can be controlled using limit and start query parameters. If a lead contains custom fields, the fields' values will be included in the response in the same format as with the Deals endpoints. If a custom field's value hasn't been set for the lead, it won't appear in the response. Please note that leads do not have a separate set of custom fields, instead they inherit the custom fields' structure from deals.

    API v1
    Cost

    40

    Request
    GET

    /v1/leads/archived

    Query parameters

    limit

    integer

    For pagination, the limit of entries to be returned. If not provided, 100 items will be returned.

    start

    integer

    For pagination, the position that represents the first result for the page

    owner_id

    integer

    If supplied, only leads matching the given user will be returned. However, filter_id takes precedence over owner_id when supplied.

    person_id

    integer

    If supplied, only leads matching the given person will be returned. However, filter_id takes precedence over person_id when supplied.

    organization_id

    integer

    If supplied, only leads matching the given organization will be returned. However, filter_id takes precedence over organization_id when supplied.

    filter_id

    integer

    The ID of the filter to use

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

    Values

    id

    title

    owner_id

    creator_id

    was_seen

    expected_close_date

    next_activity_id

    add_time

    update_time

    Response
    200

    OK

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

      Get one lead

      Copy link

      Returns details of a specific lead. If a lead contains custom fields, the fields' values will be included in the response in the same format as with the Deals endpoints. If a custom field's value hasn't been set for the lead, it won't appear in the response. Please note that leads do not have a separate set of custom fields, instead they inherit the custom fields’ structure from deals.

      API v1
      Cost

      2

      Request
      GET

      /v1/leads/{id}

      Path parameters

      id

      string

      required

      The ID of the lead

      Format

      uuid

      Response
      200

      OK

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

        List permitted users

        Copy link

        Lists the users permitted to access a lead.

        API v1
        Cost

        10

        Request
        GET

        /v1/leads/{id}/permittedUsers

        Path parameters

        id

        string

        required

        The ID of the lead

        Response
        200

        OK

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

          Search leads

          Copy link

          Searches all leads by title, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope. Found leads can be filtered by the person ID and the organization ID.

          API v1
          API v2
          Cost

          20

          Request
          GET

          /api/v2/leads/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.

          Values

          custom_fields

          notes

          title

          exact_match

          boolean

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

          person_id

          integer

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

          organization_id

          integer

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

          include_fields

          string

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

          Values

          lead.was_seen

          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 Lead conversion status (BETA)

              Copy link

              Returns data about the conversion. Status is always present and its value (not_started, running, completed, failed, rejected) represents the current state of the conversion. Deal ID is only present if the conversion was successfully finished. This data is only temporary and removed after a few days.

              API v2

              Endpoint is in beta

              Cost

              1

              Request
              GET

              /api/v2/leads/{id}/convert/status/{conversion_id}

              Path parameters

              id

              string

              required

              The ID of a lead

              Format

              uuid

              conversion_id

              string

              required

              The ID of the conversion

              Format

              uuid

              Response
              200

              OK

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

                Add a lead

                Copy link

                Creates a lead. A lead always has to be linked to a person or an organization or both. All leads created through the Pipedrive API will have a lead source and origin set to API. Here's the tutorial for adding a lead. If a lead contains custom fields, the fields' values will be included in the response in the same format as with the Deals endpoints. If a custom field's value hasn't been set for the lead, it won't appear in the response. Please note that leads do not have a separate set of custom fields, instead they inherit the custom fields' structure from deals. See an example given in the updating custom fields' values tutorial.

                API v1
                Cost

                10

                Request
                POST

                /v1/leads

                Body parameters

                application/json

                title

                string

                required

                The name of the lead

                owner_id

                integer

                The ID of the user which will be the owner of the created lead. If not provided, the user making the request will be used.

                label_ids

                array

                The IDs of the lead labels which will be associated with the lead

                person_id

                integer

                The ID of a person which this lead will be linked to. If the person does not exist yet, it needs to be created first. This property is required unless organization_id is specified.

                organization_id

                integer

                The ID of an organization which this lead will be linked to. If the organization does not exist yet, it needs to be created first. This property is required unless person_id is specified.

                value

                object

                The potential value of the lead represented by a JSON object: { "amount": 200, "currency": "EUR" }. Both amount and currency are required.

                expected_close_date

                string

                The date of when the deal which will be created from the lead is expected to be closed. In ISO 8601 format: YYYY-MM-DD.

                Format

                date

                visible_to

                string

                The visibility of the lead. 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

                was_seen

                boolean

                A flag indicating whether the lead was seen by someone in the Pipedrive UI

                origin_id

                string

                The optional ID to further distinguish the origin of the lead - e.g. Which API integration created this lead. If omitted, origin_id will be set to null.

                channel

                integer

                The ID of Marketing channel this lead was created from. Provided value must be one of the channels configured for your company. You can fetch allowed values with GET /v1/dealFields. If omitted, channel will be set to null.

                channel_id

                string

                The optional ID to further distinguish the Marketing channel. If omitted, channel_id will be set to null.

                Response
                201

                Created

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

                  Convert a lead to a deal (BETA)

                  Copy link

                  Initiates a conversion of a lead to a deal. The return value is an ID of a job that was assigned to perform the conversion. Related entities (notes, files, emails, activities, ...) are transferred during the process to the target entity. If the conversion is successful, the lead is marked as deleted. To retrieve the created entity ID and the result of the conversion, call the /api/v2/leads/{lead_id}/convert/status/{conversion_id} endpoint.

                  API v2

                  Endpoint is in beta

                  Cost

                  40

                  Request
                  POST

                  /api/v2/leads/{id}/convert/deal

                  Path parameters

                  id

                  string

                  required

                  The ID of the lead to convert

                  Format

                  uuid

                  Body parameters

                  application/json

                  stage_id

                  integer

                  The ID of a stage the created deal will be added to. Please note that a pipeline will be assigned automatically based on the stage_id. If omitted, the deal will be placed in the first stage of the default pipeline.

                  pipeline_id

                  integer

                  The ID of a pipeline the created deal will be added to. By default, the deal will be added to the first stage of the specified pipeline. Please note that pipeline_id and stage_id should not be used together as pipeline_id will be ignored.

                  Response
                  200

                  OK

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

                    Update a lead

                    Copy link

                    Updates one or more properties of a lead. Only properties included in the request will be updated. Send null to unset a property (applicable for example for value, person_id or organization_id). If a lead contains custom fields, the fields' values will be included in the response in the same format as with the Deals endpoints. If a custom field's value hasn't been set for the lead, it won't appear in the response. Please note that leads do not have a separate set of custom fields, instead they inherit the custom fields’ structure from deals. See an example given in the updating custom fields’ values tutorial.

                    API v1
                    Cost

                    10

                    Request
                    PATCH

                    /v1/leads/{id}

                    Path parameters

                    id

                    string

                    required

                    The ID of the lead

                    Format

                    uuid

                    Body parameters

                    application/json

                    title

                    string

                    The name of the lead

                    owner_id

                    integer

                    The ID of the user which will be the owner of the created lead. If not provided, the user making the request will be used.

                    label_ids

                    array

                    The IDs of the lead labels which will be associated with the lead

                    person_id

                    integer

                    The ID of a person which this lead will be linked to. If the person does not exist yet, it needs to be created first. A lead always has to be linked to a person or organization or both.

                    organization_id

                    integer

                    The ID of an organization which this lead will be linked to. If the organization does not exist yet, it needs to be created first. A lead always has to be linked to a person or organization or both.

                    is_archived

                    boolean

                    A flag indicating whether the lead is archived or not

                    value

                    object

                    The potential value of the lead represented by a JSON object: { "amount": 200, "currency": "EUR" }. Both amount and currency are required.

                    expected_close_date

                    string

                    The date of when the deal which will be created from the lead is expected to be closed. In ISO 8601 format: YYYY-MM-DD.

                    Format

                    date

                    visible_to

                    string

                    The visibility of the lead. 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

                    was_seen

                    boolean

                    A flag indicating whether the lead was seen by someone in the Pipedrive UI

                    channel

                    integer

                    The ID of Marketing channel this lead was created from. Provided value must be one of the channels configured for your company which you can fetch with GET /v1/dealFields.

                    channel_id

                    string

                    The optional ID to further distinguish the Marketing channel.

                    Response
                    200

                    OK

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

                      Delete a lead

                      Copy link

                      Deletes a specific lead.

                      API v1
                      Cost

                      6

                      Request
                      DELETE

                      /v1/leads/{id}

                      Path parameters

                      id

                      string

                      required

                      The ID of the lead

                      Format

                      uuid

                      Response
                      200

                      OK

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

                        Subscribe to Pipedrive’s Developer Newsletter