openapi: 3.0.1
info:
title: Pipedrive API v1 Activities Leads API
version: 1.0.0
description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.
'
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: Leads
description: '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`).
'
paths:
/leads:
get:
security:
- api_key: []
- oauth2:
- leads:read
- leads:full
tags:
- Leads
summary: Get all leads
description: '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.
'
x-token-cost: 20
operationId: getLeads
parameters:
- in: query
name: limit
description: For pagination, the limit of entries to be returned. If not provided, 100 items will be returned.
schema:
type: integer
example: 100
- in: query
name: start
description: For pagination, the position that represents the first result for the page
schema:
type: integer
example: 0
- in: query
name: owner_id
description: If supplied, only leads matching the given user will be returned. However, `filter_id` takes precedence over `owner_id` when supplied.
schema:
type: integer
example: 1
- in: query
name: person_id
description: If supplied, only leads matching the given person will be returned. However, `filter_id` takes precedence over `person_id` when supplied.
schema:
type: integer
example: 1
- in: query
name: organization_id
description: If supplied, only leads matching the given organization will be returned. However, `filter_id` takes precedence over `organization_id` when supplied.
schema:
type: integer
example: 1
- in: query
name: filter_id
description: The ID of the filter to use
schema:
type: integer
example: 1
- in: query
name: updated_since
description: If set, only leads with an `update_time` later than or equal to this time are returned. In ISO 8601 format, e.g. 2025-01-01T10:20:00Z.
schema:
type: string
example: '2025-01-01T10:20:00Z'
- in: query
name: sort
description: 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).
schema:
type: string
enum:
- id
- title
- owner_id
- creator_id
- was_seen
- expected_close_date
- next_activity_id
- add_time
- update_time
responses:
'200':
description: Successful response containing payload in the `data` field
content:
application/json:
schema:
title: GetLeadsResponse
type: object
properties:
success:
type: boolean
data:
type: array
items:
type: object
title: Lead
properties:
id:
type: string
format: uuid
description: The unique ID of the lead in the UUID format
title:
type: string
description: The title of the lead
owner_id:
type: integer
description: The ID of the user who owns the lead
creator_id:
type: integer
description: The ID of the user who created the lead
label_ids:
type: array
description: The IDs of the lead labels which are associated with the lead
items:
type: string
format: uuid
person_id:
type: integer
nullable: true
description: The ID of a person which this lead is linked to
organization_id:
type: integer
nullable: true
description: The ID of an organization which this lead is linked to
source_name:
type: string
description: 'Defines where the lead comes from. Will be `API` if the lead was created through the Public API and will be `Manually created` if the lead was created manually through the UI.
'
origin:
type: string
description: The way this Lead was created. `origin` field is set by Pipedrive when Lead is created and cannot be changed.
origin_id:
type: string
nullable: true
description: The optional ID to further distinguish the origin of the lead - e.g. Which API integration created this Lead.
channel:
type: integer
nullable: true
description: The ID of your Marketing channel this Lead was created from. Recognized Marketing channels can be configured in your <a href="https://app.pipedrive.com/settings/fields" target="_blank" rel="noopener noreferrer">Company settings</a>.
channel_id:
type: string
nullable: true
description: The optional ID to further distinguish the Marketing channel.
source_deal_id:
type: integer
nullable: true
description: The ID of the deal if the lead was converted from a deal.
is_archived:
type: boolean
description: A flag indicating whether the lead is archived or not
was_seen:
type: boolean
description: A flag indicating whether the lead was seen by someone in the Pipedrive UI
value:
type: object
nullable: true
description: 'The potential value of the lead represented by a JSON object: `{ "amount": 200, "currency": "EUR" }`. Both amount and currency are required.'
required:
- amount
- currency
properties:
amount:
type: number
currency:
type: string
expected_close_date:
type: string
format: date
nullable: true
description: '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.'
next_activity_id:
type: integer
nullable: true
description: The ID of the next activity associated with the lead
add_time:
type: string
description: 'The date and time of when the lead was created. In ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.'
format: date-time
update_time:
type: string
description: 'The date and time of when the lead was last updated. In ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.'
format: date-time
visible_to:
type: string
allOf:
- type: string
enum:
- '1'
- '3'
- '5'
- '7'
description: 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.<table><tr><th>Value</th><th>Description</th></tr><tr><td>`1`</td><td>Owner & followers (private)</td></tr><tr><td>`3`</td><td>Entire company (shared)</td></tr></table>
cc_email:
type: string
description: The BCC email of the lead
additional_data:
description: The additional data of the list
type: object
properties:
start:
type: integer
description: Pagination start
limit:
type: integer
description: Items shown per page
more_items_in_collection:
type: boolean
description: If there are more list items in the collection than displayed or not
example:
success: true
data:
- id: adf21080-0e10-11eb-879b-05d71fb426ec
title: Jane Doe Lead
owner_id: 1
creator_id: 1
label_ids:
- f08b42a0-4e75-11ea-9643-03698ef1cfd6
- f08b42a1-4e75-11ea-9643-03698ef1cfd6
person_id: 1092
organization_id: null
source_name: API
origin: API
origin_id: null
channel: 52
channel_id: Jun23 Billboards
is_archived: false
was_seen: false
value:
amount: 999
currency: USD
expected_close_date: null
next_activity_id: 1
add_time: '2020-10-14T11:30:36.551Z'
update_time: '2020-10-14T11:30:36.551Z'
visible_to: '3'
cc_email: company+1+leadntPaYKA5QRxXkh6WMNHiGh@dev.pipedrivemail.com
post:
security:
- api_key: []
- oauth2:
- leads:full
tags:
- Leads
summary: Add a lead
description: 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 <a href="https://pipedrive.readme.io/docs/adding-a-lead" target="_blank" rel="noopener noreferrer">adding a lead</a>. 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 <a href="https://pipedrive.readme.io/docs/updating-custom-field-value" target="_blank" rel="noopener noreferrer">updating custom fields' values tutorial</a>.
x-token-cost: 10
operationId: addLead
requestBody:
content:
application/json:
schema:
title: addLeadRequest
type: object
required:
- title
properties:
title:
type: string
description: The name of the lead
owner_id:
type: integer
description: 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:
type: array
description: The IDs of the lead labels which will be associated with the lead
items:
type: string
format: uuid
person_id:
type: integer
description: 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:
type: integer
description: 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:
type: object
nullable: true
description: 'The potential value of the lead represented by a JSON object: `{ "amount": 200, "currency": "EUR" }`. Both amount and currency are required.'
required:
- amount
- currency
properties:
amount:
type: number
currency:
type: string
expected_close_date:
type: string
format: date
description: '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.'
visible_to:
type: string
allOf:
- type: string
enum:
- '1'
- '3'
- '5'
- '7'
description: '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 <a href="https://support.pipedrive.com/en/article/visibility-groups" target="_blank" rel="noopener noreferrer">here</a>.<h4>Light / Growth and Professional plans</h4><table><tr><th style="width: 40px">Value</th><th>Description</th></tr><tr><td>`1`</td><td>Owner & followers</td><tr><td>`3`</td><td>Entire company</td></tr></table><h4>Premium / Ultimate plan</h4><table><tr><th style="width: 40px">Value</th><th>Description</th></tr><tr><td>`1`</td><td>Owner only</td><tr><td>`3`</td><td>Owner''s visibility group</td></tr><tr><td>`5`</td><td>Owner''s visibility group and sub-groups</td></tr><tr><td>`7`</td><td>Entire company</td></tr></table>'
was_seen:
type: boolean
description: A flag indicating whether the lead was seen by someone in the Pipedrive UI
origin_id:
type: string
nullable: true
description: 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:
type: integer
nullable: true
description: 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 <a href="https://developers.pipedrive.com/docs/api/v1/DealFields#getDealField" target="_blank" rel="noopener noreferrer">GET /v1/dealFields</a>. If omitted, channel will be set to null.
channel_id:
type: string
nullable: true
description: The optional ID to further distinguish the Marketing channel. If omitted, `channel_id` will be set to null.
responses:
'201':
description: Successful response containing payload in the `data` field
content:
application/json:
schema:
title: GetLeadResponse
type: object
properties:
success:
type: boolean
data:
type: object
title: Lead
properties:
id:
type: string
format: uuid
description: The unique ID of the lead in the UUID format
title:
type: string
description: The title of the lead
owner_id:
type: integer
description: The ID of the user who owns the lead
creator_id:
type: integer
description: The ID of the user who created the lead
label_ids:
type: array
description: The IDs of the lead labels which are associated with the lead
items:
type: string
format: uuid
person_id:
type: integer
nullable: true
description: The ID of a person which this lead is linked to
organization_id:
type: integer
nullable: true
description: The ID of an organization which this lead is linked to
source_name:
type: string
description: 'Defines where the lead comes from. Will be `API` if the lead was created through the Public API and will be `Manually created` if the lead was created manually through the UI.
'
origin:
type: string
description: The way this Lead was created. `origin` field is set by Pipedrive when Lead is created and cannot be changed.
origin_id:
type: string
nullable: true
description: The optional ID to further distinguish the origin of the lead - e.g. Which API integration created this Lead.
channel:
type: integer
nullable: true
description: The ID of your Marketing channel this Lead was created from. Recognized Marketing channels can be configured in your <a href="https://app.pipedrive.com/settings/fields" target="_blank" rel="noopener noreferrer">Company settings</a>.
channel_id:
type: string
nullable: true
description: The optional ID to further distinguish the Marketing channel.
source_deal_id:
type: integer
nullable: true
description: The ID of the deal if the lead was converted from a deal.
is_archived:
type: boolean
description: A flag indicating whether the lead is archived or not
was_seen:
type: boolean
description: A flag indicating whether the lead was seen by someone in the Pipedrive UI
value:
type: object
nullable: true
description: 'The potential value of the lead represented by a JSON object: `{ "amount": 200, "currency": "EUR" }`. Both amount and currency are required.'
required:
- amount
- currency
properties:
amount:
type: number
currency:
type: string
expected_close_date:
type: string
format: date
nullable: true
description: '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.'
next_activity_id:
type: integer
nullable: true
description: The ID of the next activity associated with the lead
add_time:
type: string
description: 'The date and time of when the lead was created. In ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.'
format: date-time
update_time:
type: string
description: 'The date and time of when the lead was last updated. In ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.'
format: date-time
visible_to:
type: string
allOf:
- type: string
enum:
- '1'
- '3'
- '5'
- '7'
description: 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.<table><tr><th>Value</th><th>Description</th></tr><tr><td>`1`</td><td>Owner & followers (private)</td></tr><tr><td>`3`</td><td>Entire company (shared)</td></tr></table>
cc_email:
type: string
description: The BCC email of the lead
example:
success: true
data:
id: adf21080-0e10-11eb-879b-05d71fb426ec
title: Jane Doe Lead
owner_id: 1
creator_id: 1
label_ids:
- f08b42a0-4e75-11ea-9643-03698ef1cfd6
- f08b42a1-4e75-11ea-9643-03698ef1cfd6
person_id: 1092
organization_id: null
source_name: API
origin: API
origin_id: null
channel: 52
channel_id: Jun23 Billboards
is_archived: false
was_seen: false
value:
amount: 999
currency: USD
expected_close_date: null
next_activity_id: 1
add_time: '2020-10-14T11:30:36.551Z'
update_time: '2020-10-14T11:30:36.551Z'
visible_to: '3'
cc_email: company+1+leadntPaYKA5QRxXkh6WMNHiGh@dev.pipedrivemail.com
/leads/archived:
get:
security:
- api_key: []
- oauth2:
- leads:read
- leads:full
tags:
- Leads
summary: Get all archived leads
description: '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.
'
x-token-cost: 40
operationId: getArchivedLeads
parameters:
- in: query
name: limit
description: For pagination, the limit of entries to be returned. If not provided, 100 items will be returned.
schema:
type: integer
example: 100
- in: query
name: start
description: For pagination, the position that represents the first result for the page
schema:
type: integer
example: 0
- in: query
name: owner_id
description: If supplied, only leads matching the given user will be returned. However, `filter_id` takes precedence over `owner_id` when supplied.
schema:
type: integer
example: 1
- in: query
name: person_id
description: If supplied, only leads matching the given person will be returned. However, `filter_id` takes precedence over `person_id` when supplied.
schema:
type: integer
example: 1
- in: query
name: organization_id
description: If supplied, only leads matching the given organization will be returned. However, `filter_id` takes precedence over `organization_id` when supplied.
schema:
type: integer
example: 1
- in: query
name: filter_id
description: The ID of the filter to use
schema:
type: integer
example: 1
- in: query
name: sort
description: 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).
schema:
type: string
enum:
- id
- title
- owner_id
- creator_id
- was_seen
- expected_close_date
- next_activity_id
- add_time
- update_time
responses:
'200':
description: Successful response containing payload in the `data` field
content:
application/json:
schema:
title: GetLeadsResponse
type: object
properties:
success:
type: boolean
data:
type: array
items:
type: object
title: Lead
properties:
id:
type: string
format: uuid
description: The unique ID of the lead in the UUID format
title:
type: string
description: The title of the lead
owner_id:
type: integer
description: The ID of the user who owns the lead
creator_id:
type: integer
description: The ID of the user who created the lead
label_ids:
type: array
description: The IDs of the lead labels which are associated with the lead
items:
type: string
format: uuid
person_id:
type: integer
nullable: true
description: The ID of a person which this lead is linked to
organization_id:
type: integer
nullable: true
description: The ID of an organization which this lead is linked to
source_name:
type: string
description: 'Defines where the lead comes from. Will be `API` if the lead was created through the Public API and will be `Manually created` if the lead was created manually through the UI.
'
origin:
type: string
description: The way this Lead was created. `origin` field is set by Pipedrive when Lead is created and cannot be changed.
origin_id:
type: string
nullable: true
description: The optional ID to further distinguish the origin of the lead - e.g. Which API integration created this Lead.
channel:
type: integer
nullable: true
description: The ID of your Marketing channel this Lead was created from. Recognized Marketing channels can be configured in your <a href="https://app.pipedrive.com/settings/fields" target="_blank" rel="noopener noreferrer">Company settings</a>.
channel_id:
type: string
nullable: true
description: The optional ID to further distinguish the Marketing channel.
source_deal_id:
type: integer
nullable: true
description: The ID of the deal if the lead was converted from a deal.
is_archived:
type: boolean
description: A flag indicating whether the lead is archived or not
was_seen:
type: boolean
description: A flag indicating whether the lead was seen by someone in the Pipedrive UI
value:
type: object
nullable: true
description: 'The potential value of the lead represented by a JSON object: `{ "amount": 200, "currency": "EUR" }`. Both amount and currency are required.'
required:
- amount
- currency
properties:
amount:
type: number
currency:
type: string
expected_close_date:
type: string
format: date
nullable: true
description: '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.'
next_activity_id:
type: integer
nullable: true
description: The ID of the next activity associated with the lead
add_time:
type: string
description: 'The date and time of when the lead was created. In ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.'
format: date-time
update_time:
type: string
description: 'The date and time of when the lead was last updated. In ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.'
format: date-time
visible_to:
type: string
allOf:
- type: string
enum:
- '1'
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-leads-api-openapi.yml