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
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.
Cost
20
Request
/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
OK
Expand all
Copy code- true
- [ ... ]▶
Get all archived leads
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.
Cost
40
Request
/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
OK
Expand allCopy code- true
- [ ... ]▶
Get one lead
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.
Cost
2
Request
/v1/leads/{id}
Path parameters
id
string
required
The ID of the lead
Format
uuid
Response
OK
Expand allCopy code- true
- { ... }▶
List permitted users
Lists the users permitted to access a lead.
Cost
10
Request
/v1/leads/{id}/permittedUsers
Path parameters
id
string
required
The ID of the lead
Response
OK
Expand allCopy code- true
- [ ... ]▶
Search leads
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.
Cost
20
Request
/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
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Get Lead conversion status (BETA)
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.
Cost
1
Request
/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
OK
Expand allCopy code- true
- { ... }▶
- null
Add a lead
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.
Cost
10
Request
/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
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Professional / Enterprise plan
| Value | Description |
|---|---|
1 | Owner only |
3 | Owner's visibility group |
5 | Owner's visibility group and sub-groups |
7 | Entire 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
Created
Expand allCopy code- true
- { ... }▶
Convert a lead to a deal (BETA)
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.
Cost
40
Request
/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
OK
Expand allCopy code- true
- { ... }▶
- null
Update a lead
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.
Cost
10
Request
/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
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Professional / Enterprise plan
| Value | Description |
|---|---|
1 | Owner only |
3 | Owner's visibility group |
5 | Owner's visibility group and sub-groups |
7 | Entire 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
OK
Expand allCopy code- true
- { ... }▶
Delete a lead
Deletes a specific lead.
Cost
6
Request
/v1/leads/{id}
Path parameters
id
string
required
The ID of the lead
Format
uuid
Response
OK
Expand allCopy code- true
- { ... }▶