Pipedrive Persons API
Manage person (contact) records — names, emails, phones, social profiles — associated with deals and organizations.
OpenAPI Specification
openapi: 3.0.1
info:
title: Pipedrive API v1
version: 1.0.0
servers:
- url: 'https://api.pipedrive.com/v1'
tags:
- name: Activities
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.
- name: ActivityFields
description: |
Activity fields represent different fields that an activity has.
- name: ActivityTypes
description: |
Activity types represent different kinds of activities that can be stored. Each activity type is presented to the user with an icon and a name. Additionally, a color can be defined (not implemented in the Pipedrive app as of today). Activity types are linked to activities via `ActivityType.key_string = Activity.type`. The `key_string` will be generated by the API based on the given name of the activity type upon creation, and cannot be changed. Activity types should be presented to the user in an ordered manner, using the `ActivityType.order_nr` value.
- name: Billing
description: |
Billing is responsible for handling your subscriptions, payments, plans and add-ons.
- name: CallLogs
description: |
Call logs describe the outcome of a phone call managed by an integrated provider. Since these logs are also considered activities, they can be associated with a deal or a lead, a person and/or an organization. Call logs do differ from other activities, as they only receive the information needed to describe the phone call.
- name: Channels
description: |
Channels API allows you to integrate your existing messaging channels into Pipedrive through [Messaging app extension](https://pipedrive.readme.io/docs/messaging-app-extension). It enables you to manage and interact with the channel’s conversations, participants and messages inside Pipedrive Messaging inbox: get the historical conversation, receive and send new messages. These endpoints are accessible only through **Messengers integration** OAuth scope together with Messaging manifest in building the [Messaging app extension](https://pipedrive.readme.io/docs/messaging-app-extension).
- name: Currencies
description: |
Supported currencies which can be used to represent the monetary value of a deal, or a value of any monetary type custom field. The `Currency.code` field must be used to point to a currency. `Currency.code` is the ISO-4217 format currency code for non-custom currencies. You can differentiate custom and non-custom currencies using the `is_custom_flag` property. For custom currencies, it is intended that the formatted sums are displayed in the UI using the following format: [sum][non-breaking space character][currency.symbol], for example: 500 users. Custom currencies cannot be added or removed via the API yet — rather the admin users of the account must configure them from the Pipedrive app.
- name: DealFields
description: |
Deal fields represent the near-complete schema for a deal in the context of the company of the authorized user. Each company can have a different schema for their deals, with various custom fields. In the context of using deal fields as a schema for defining the data fields of a deal, it must be kept in mind that some types of custom fields can have additional data fields which are not separate deal fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of deal fields. For example, if there is a monetary field with the key `ffk9s9` stored on the account, `ffk9s9` would hold the numeric value of the field, and `ffk9s9_currency` would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one deal and list its keys.
- name: Deals
description: |
Deals represent ongoing, lost or won sales to an organization or to a person. Each deal has a monetary value and must be placed in a stage. Deals can be owned by a user, and followed by one or many users. Each deal consists of standard data fields but can also contain a number of custom fields. The custom fields can be recognized by long hashes as keys. These hashes can be mapped against `DealField.key`. The corresponding label for each such custom field can be obtained from `DealField.name`.
- name: Files
description: |
Files are documents of any kind (images, spreadsheets, text files, etc.) that are uploaded to Pipedrive, and usually associated with a particular deal, person, organization, product, note or activity. Remote files can only be associated with a particular deal, person or organization. Note that the API currently does not support downloading files although it lets you retrieve a file’s meta-info along with a URL which can be used to download the file by using a standard HTTP GET request.
- name: Filters
description: |
Each filter is essentially a set of data validation conditions. A filter of the same kind can be applied when fetching a list of deals, leads, persons, organizations or products in the context of a pipeline. Filters are limited to a maximum of 16 conditions. When applied, only items matching the conditions of the filter are returned. Detailed definitions of filter conditions and additional functionality is not yet available.
- name: Goals
description: |
Goals help your team meet your sales targets. There are three types of goals - company, team and user.
- name: ItemSearch
description: |
Ordered reference objects, pointing to either deals, persons, organizations, leads, products, files or mail attachments.
- name: LeadFields
description: |
Lead fields represent the near-complete schema for a lead in the context of the company of the authorized user. Each company can have a different schema for their leads, with various custom fields. In the context of using lead fields as a schema for defining the data fields of a lead, it must be kept in mind that some types of custom fields can have additional data fields which are not separate lead fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of lead fields. For example, if there is a monetary field with the key `ffk9s9` stored on the account, `ffk9s9` would hold the numeric value of the field, and `ffk9s9_currency` would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one lead and list its keys.
- name: LeadLabels
description: |
Lead labels allow you to visually categorize your leads. There are three default lead labels: hot, cold, and warm, but you can add as many new custom labels as you want.
- name: LeadSources
description: |
A lead source indicates where your lead came from. Currently, these are the possible lead sources: `Manually created`, `Deal`, `Web forms`, `Prospector`, `Leadbooster`, `Live chat`, `Import`, `Website visitors`, `Workflow automation`, and `API`. Lead sources are pre-defined and cannot be edited. Please note that leads sourced from the Chatbot feature are assigned the value `Leadbooster`. Please also note that this list is not final and new sources may be added as needed.
- 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`).
- name: LegacyTeams
description: |
Legacy teams allow you to form groups of users withing the organization for more efficient management. Previously Legacy Teams were called Teams and occupied the `v1/teams*` path. They're being deprecated because we are preparing for an upgraded version of the Teams API, which requires migrating the current functionality to a new path URL `v1/legacyTeams*`. The functionality and [OAuth scopes](https://pipedrive.readme.io/docs/marketplace-scopes-and-permissions-explanations) of all the Teams API endpoints will remain the same.
- name: Mailbox
description: |
Mailbox was designed to be the email control hub inside Pipedrive. Pipedrive supports all major providers (including Gmail, Outlook and also custom IMAP/SMTP). There are 2 options for syncing user emails: 2-way sync: Mail Connection is established with the mail provider (example Gmail). There can be only 1 active Mail Connection per user in company. 1-way sync: SmartBCC feature which stores the copies of email messages to Pipedrive by adding the SmartBCC specific address to mail recipients.
- name: Meetings
description: |
Meetings API allows integrating video calling apps into Pipedrive through [Video Calling App extension](https://pipedrive.readme.io/docs/video-calling-app-extension). It enables you to manage and interact with your video calls and meetings inside Pipedrive. These endpoints are accessible only through apps with video calls integration [OAuth scope](https://pipedrive.readme.io/docs/marketplace-scopes-and-permissions-explanations).
- name: NoteFields
description: |
Note fields represent different fields that a note has.
- name: Notes
description: |
Notes are pieces of textual (HTML-formatted) information that can be attached to deals, persons and organizations. Notes are usually displayed in the UI in chronological order – newest first – and in context with other updates regarding the item they are attached to. The maximum note size is approximately 100,000 characters (or 100KB per note).
- name: Oauth
description: |
Using OAuth 2.0 is necessary for developing apps that are available in the Pipedrive Marketplace. Authorization via OAuth 2.0 is a well-known and stable way to get fine-grained access to an API. To retrieve OAuth2 tokens you should send requests to the `https://oauth.pipedrive.com` domain. After registering the app, you must add the necessary server-side logic to your app to establish the OAuth flow. Please read more about authorization step on the [Pipedrive Developers page](https://pipedrive.readme.io/docs/marketplace-oauth-authorization).
- name: OrganizationFields
description: |
Organization fields represent the near-complete schema for an organization in the context of the company of the authorized user. Each company can have a different schema for their organizations, with various custom fields. In the context of using organization fields as a schema for defining the data fields of an organization, it must be kept in mind that some types of custom fields can have additional data fields which are not separate organization fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of organization fields. For example, if there is a monetary field with the key `ffk9s9` stored on the account, `ffk9s9` would hold the numeric value of the field, and `ffk9s9_currency` would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one organization and list its keys.
- name: OrganizationRelationships
description: |
Organization relationships represent how different organizations are related to each other. The relationship can be hierarchical (parent-child companies) or lateral as defined by the `type` field - either `parent` or `related`.
- name: Organizations
description: |
Organizations are companies and other kinds of organizations you are making deals with. Persons can be associated with organizations so that each organization can contain one or more persons.
- name: PermissionSets
description: |
Permission sets define what users in the account can do: which actions they are allowed to perform and which features they can access. Permission sets are app-specific, where apps are large parts of functionality, e.g., sales app, which allows accessing sales data, global permissions, which oversee cross-product features (for example contacts, insights, products) or account settings, which provides access to billing, user management, company settings and security center. Some permission sets with types such as admin and regular are pre-created for the account, while other custom ones can be created by users (depending on the tier the account is on).
- name: PersonFields
description: |
Person fields represent the near-complete schema for a person in the context of the company of the authorized user. Each company can have a different schema for their persons, with various custom fields. In the context of using person fields as a schema for defining the data fields of a person, it must be kept in mind that some types of custom fields can have additional data fields which are not separate person fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of person fields. For example, if there is a monetary field with the key `ffk9s9` stored on the account, `ffk9s9` would hold the numeric value of the field, and `ffk9s9_currency` would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one person and list its keys.
- name: Persons
description: |
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.
- name: Pipelines
description: |
Pipelines are essentially ordered collections of stages.
- name: ProductFields
description: |
Product fields represent the near-complete schema for a product in the context of the company of the authorized user. Each company can have a different schema for their products, with various custom fields. In the context of using product fields as a schema for defining the data fields of a product, it must be kept in mind that some types of custom fields can have additional data fields which are not separate product fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of product fields. For example, if there is a monetary field with the key `ffk9s9` stored on the account, `ffk9s9` would hold the numeric value of the field, and `ffk9s9_currency` would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one product and list its keys.
- name: Products
description: |
Products are the goods or services you are dealing with. Each product can have N different price points - firstly, each product can have a price in N different currencies, and secondly, each product can have N variations of itself, each having N prices in different currencies. Note that only one price per variation per currency is supported. Products can be instantiated to deals. In the context of instatiation, a custom price, quantity, duration and discount can be applied.
- name: Projects
description: |
Projects represent ongoing, completed or canceled projects attached to an organization, person or to deals. Each project has an owner and must be placed in a phase. Each project consists of standard data fields but can also contain a number of custom fields. The custom fields can be recognized by long hashes as keys.
- name: ProjectBoards
description: |
Project boards are used to organize projects into different phases. Each board contains phases that define the workflow for projects.
- name: ProjectPhases
description: |
Project phases represent the stages within a project board. Each phase belongs to a board and defines a step in the project workflow.
- name: ProjectTemplates
description: |
Project templates allow you to have reusable and dynamic structure to simplify creation of a project. Project template can contain information about activities, tasks and groups that will be used when creating a project.
- name: Recents
description: |
Recent changes across all item types in Pipedrive (deals, persons, etc).
- name: Roles
description: |
Roles are a part of the Visibility groups’ feature that allow the admin user to categorize other users and dictate what items they will be allowed access to see.
- name: Stages
description: |
Stage is a logical component of a pipeline, and essentially a bucket that can hold a number of deals. In the context of the pipeline a stage belongs to, it has an order number which defines the order of stages in that pipeline.
- name: Tasks
description: |
Tasks represent actions that need to be completed and must be associated with a project. Tasks have an optional due date, can be assigned to a user and can have subtasks.
- name: UserConnections
description: |
Manage user connections.
- name: UserSettings
description: |
View user settings.
- name: Users
description: |
Users are people with access to your Pipedrive account. A user may belong to one or many Pipedrive accounts, so deleting a user from one Pipedrive account will not remove the user from the data store if he/she is connected to multiple accounts. Users should not be confused with persons.
- name: Webhooks
description: 'See <a href="https://pipedrive.readme.io/docs/guide-for-webhooks-v2?ref=api_reference" target="_blank" rel="noopener noreferrer">the guide for Webhooks</a> for more information.'
paths:
/activityFields:
get:
summary: Get all activity fields
description: Returns all activity fields.
x-token-cost: 20
operationId: getActivityFields
tags:
- ActivityFields
security:
- api_key: []
- oauth2:
- 'activities:read'
- 'activities:full'
responses:
'200':
description: Success
content:
application/json:
schema:
title: GetFieldsResponse
allOf:
- title: baseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
- title: FieldsResponse
- type: object
properties:
data:
type: array
items:
type: object
title: GetField
allOf:
- title: Field
type: object
properties:
id:
type: integer
nullable: true
description: The ID of the field. Value is `null` in case of subfields.
key:
type: string
description: The key of the field. For custom fields this is generated upon creation.
name:
type: string
description: The name of the field
order_nr:
type: integer
description: The order number of the field
field_type:
allOf:
- type: string
enum:
- address
- date
- daterange
- double
- enum
- monetary
- org
- people
- phone
- set
- text
- time
- timerange
- user
- varchar
- varchar_auto
- visible_to
description: 'The type of the field<table><tr><th>Value</th><th>Description</th></tr><tr><td>`address`</td><td>Address field</td></tr><tr><td>`date`</td><td>Date (format YYYY-MM-DD)</td></tr><tr><td>`daterange`</td><td>Date-range field (has a start date and end date value, both YYYY-MM-DD)</td></tr><tr><td>`double`</td><td>Numeric value</td></tr><tr><td>`enum`</td><td>Options field with a single possible chosen option</td></tr><tr></tr><tr><td>`monetary`</td><td>Monetary field (has a numeric value and a currency value)</td></tr><tr><td>`org`</td><td>Organization field (contains an organization ID which is stored on the same account)</td></tr><tr><td>`people`</td><td>Person field (contains a person ID which is stored on the same account)</td></tr><tr><td>`phone`</td><td>Phone field (up to 255 numbers and/or characters)</td></tr><tr><td>`set`</td><td>Options field with a possibility of having multiple chosen options</td></tr><tr><td>`text`</td><td>Long text (up to 65k characters)</td></tr><tr><td>`time`</td><td>Time field (format HH:MM:SS)</td></tr><tr><td>`timerange`</td><td>Time-range field (has a start time and end time value, both HH:MM:SS)</td></tr><tr><td>`user`</td><td>User field (contains a user ID of another Pipedrive user)</td></tr><tr><td>`varchar`</td><td>Text (up to 255 characters)</td></tr><tr><td>`varchar_auto`</td><td>Autocomplete text (up to 255 characters)</td></tr><tr><td>`visible_to`</td><td>System field that keeps item''s visibility setting</td></tr></table>'
add_time:
type: string
format: date-time
description: The creation time of the field
update_time:
type: string
format: date-time
nullable: true
description: The update time of the field
last_updated_by_user_id:
type: integer
nullable: true
description: 'The ID of the user who created or most recently updated the field, only applicable for custom fields'
created_by_user_id:
type: integer
nullable: true
description: The ID of the user who created the field
active_flag:
type: boolean
description: The active flag of the field
edit_flag:
type: boolean
description: The edit flag of the field
index_visible_flag:
type: boolean
description: Not used
details_visible_flag:
type: boolean
description: Not used
add_visible_flag:
type: boolean
description: Not used
important_flag:
type: boolean
description: Not used
bulk_edit_allowed:
type: boolean
description: Whether or not the field of an item can be edited in bulk
searchable_flag:
type: boolean
description: Whether or not items can be searched by this field
filtering_allowed:
type: boolean
description: Whether or not items can be filtered by this field
sortable_flag:
type: boolean
description: Whether or not items can be sorted by this field
mandatory_flag:
type: boolean
description: Whether or not the field is mandatory
options:
type: array
nullable: true
items:
type: object
description: 'The options of the field. When there are no options, `null` is returned.'
options_deleted:
type: array
items:
type: object
description: The deleted options of the field. Only present when there is at least 1 deleted option.
is_subfield:
type: boolean
description: Whether or not the field is a subfield of another field. Only present if field is subfield.
subfields:
type: array
items:
type: object
description: The subfields of the field. Only present when the field has subfields.
- type: object
properties:
field_type:
type: string
enum:
- boolean
- double
- int
- json
- date
- daterange
- time
- timerange
- text
- varchar
- varchar_auto
- varchar_options
- address
- enum
- monetary
- phone
- set
- activity
- deal
- lead
- org
- people
- pipeline
- product
- project
- stage
- user
- billing_frequency
- picture
- price_list
- projects_board
- projects_phase
- status
- visible_to
description: List of all possible field types
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: 1
key: title
name: Title
order_nr: 2
field_type: varchar
add_time: '2019-02-04 13:58:03'
update_time: '2019-02-04 13:58:03'
last_updated_by_user_id: 1
created_by_user_id: 1
active_flag: true
edit_flag: false
index_visible_flag: true
details_visible_flag: true
add_visible_flag: true
important_flag: false
bulk_edit_allowed: true
searchable_flag: false
filtering_allowed: true
sortable_flag: true
options: null
mandatory_flag: true
- id: 2
key: 9dc80c50d78a15643bfc4ca79d76156a73a1ca0e
name: Customer Type
order_nr: 1
field_type: enum
add_time: '2019-02-04 13:58:03'
update_time: '2019-02-04 13:58:03'
last_updated_by_user_id: 1
created_by_user_id: 1
active_flag: true
edit_flag: true
index_visible_flag: true
details_visible_flag: true
add_visible_flag: false
important_flag: false
bulk_edit_allowed: true
searchable_flag: false
filtering_allowed: true
sortable_flag: true
options:
- id: 190
label: Private person
- id: 191
label: Company
- id: 192
label: Government
mandatory_flag: true
additional_data:
pagination:
start: 0
limit: 100
more_items_in_collection: false
/activityTypes:
get:
summary: Get all activity types
description: Returns all activity types.
x-token-cost: 20
operationId: getActivityTypes
tags:
- ActivityTypes
security:
- api_key: []
- oauth2:
- 'activities:read'
- 'activities:full'
- admin
responses:
'200':
description: A list of activity types
content:
application/json:
schema:
title: GetActivityTypesResponse
allOf:
- title: baseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
- type: object
properties:
data:
type: array
items:
type: object
title: ActivityType
# --- truncated at 32 KB (1733 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-v1-openapi.yml