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

/v1/leads

Returns multiple 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.

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

archived_status

string

Filtering based on archived status of a Lead. If not provided, All is used.

Values

archived

not_archived

all

Response
200

Successful response containing payload in the data field.

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

    Get one lead

    Copy link
    Copy to clipboard
    GET

    /v1/leads/{id}

    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.

    Path parameters

    id

    string

    required

    The ID of the Lead

    Format

    uuid

    Response
    200

    Successful response containing payload in the data field.

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

      Add a lead

      Copy link
      Copy to clipboard
      POST

      /v1/leads

      Creates a Lead. A Lead always has to be linked to a Person or an Organization or both. All Leads created through the Public Pipedrive API will have a Lead Source API assigned. 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 of updating custom fields’ values in this tutorial.

      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.

      note

      string

      The Lead note. Can contain some allowed HTML tags. (DEPRECATED - please create a Note object and link it to this lead via lead_id)

      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.

      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

      Response
      201

      Successful response containing payload in the data field.

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

        Delete a lead

        Copy link
        Copy to clipboard
        DELETE

        /v1/leads/{id}

        Deletes a specific Lead

        Path parameters

        id

        string

        required

        The ID of the Lead

        Format

        uuid

        Response
        200

        Successful response with id value only. Used in DELETE calls.

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

          Update a lead

          Copy link
          Copy to clipboard
          PATCH

          /v1/leads/{id}

          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 of updating custom fields’ values in this tutorial.

          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.

          note

          string

          The Lead note. Can contain some allowed HTML tags. (DEPRECATED - please use a Note object instead, until the removal of this field, we will update the first Note linked to this lead ourselves)

          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.

          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

          Response
          200

          Successful response containing payload in the data field.

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

            Subscribe to Pipedrive’s Developer Newsletter