Pipedrive

Authentication Type: API Key Description: Sales CRM platform for managing persons, deals, notes, activities, and pipelines with comprehensive API access.

Authentication

To authenticate, you'll need a Pipedrive API token:

1. Go to Settings (gear icon) > Personal preferences in your Pipedrive account
2. Click on the API tab
3. Copy your personal API token

For more details, see the Pipedrive API documentation.

Persons

Manage contacts and individuals in your Pipedrive CRM.

Search Persons

Search for persons by name, email, phone, or other fields.

Operation Type: Query (Read)

Parameters:

• term string (required): Search term to find persons
• start number (nullable): Pagination start index
• limit number (nullable): Maximum results to return

Returns:

• results array of objects: Matching persons
  • id number: Person ID
  • name string (nullable): Person name
  • email string (nullable): Primary email
  • phone string (nullable): Primary phone
  • orgId number (nullable): Organization ID
  • addTime string (nullable): Created timestamp
  • updateTime string (nullable): Updated timestamp
• hasMore boolean: Whether more results exist
• nextStart number (nullable): Next pagination start index

Example Usage:

{
  "term": "john@acme.com",
  "limit": 10
}

Get Person

Retrieve a specific person by their ID.

Operation Type: Query (Read)

Parameters:

• personId number (required): The ID of the person to retrieve

Returns:

• id number: Person ID
• name string (nullable): Full name
• firstName string (nullable): First name
• lastName string (nullable): Last name
• email string (nullable): Primary email
• phone string (nullable): Primary phone
• orgId number (nullable): Organization ID
• ownerId number (nullable): Owner user ID
• addTime string (nullable): Created timestamp
• updateTime string (nullable): Updated timestamp
• activeFlag boolean: Whether person is active

Example Usage:

{
  "personId": 12345
}

List Persons

Retrieve a paginated list of all persons.

Operation Type: Query (Read)

Parameters:

• start number (nullable): Pagination start index
• limit number (nullable): Maximum results to return

Returns:

• results array of objects: List of persons
• hasMore boolean: Whether more results exist
• nextStart number (nullable): Next pagination start index

Example Usage:

{
  "start": 0,
  "limit": 50
}

Add Person

Create a new person (contact) in your Pipedrive CRM.

Operation Type: Mutation (Write)

Parameters:

• name string (required): The name of the person
• email string (nullable): Email address
• phone string (nullable): Phone number
• orgId number (nullable): ID of the organization to link the person to
• ownerId number (nullable): ID of the user who will own the person
• visibleTo number (nullable): Visibility (1=owner only, 3=entire company)

Returns:

• id number: Created person ID
• name string (nullable): Person name
• email string (nullable): Primary email
• phone string (nullable): Primary phone
• orgId number (nullable): Organization ID
• ownerId number (nullable): Owner user ID
• addTime string (nullable): Created timestamp

Example Usage:

{
  "name": "Jane Smith",
  "email": "jane.smith@acme.com",
  "phone": "+1-555-987-6543",
  "orgId": 67890
}

Update Person

Update an existing person's information.

Operation Type: Mutation (Write)

Parameters:

• personId number (required): The ID of the person to update
• name string (nullable): New name
• email string (nullable): New email
• phone string (nullable): New phone
• orgId number (nullable): New organization ID
• ownerId number (nullable): New owner user ID

Returns:

• id number: Person ID
• name string (nullable): Updated name
• email string (nullable): Updated email
• phone string (nullable): Updated phone
• orgId number (nullable): Updated organization ID
• ownerId number (nullable): Updated owner user ID
• updateTime string (nullable): Updated timestamp

Example Usage:

{
  "personId": 12345,
  "phone": "+1-555-123-4567",
  "orgId": 67890
}

Get Person Activities

Retrieve activities (calls, meetings, tasks, etc.) associated with a person.

Operation Type: Query (Read)

Parameters:

• personId number (required): The ID of the person to get activities for
• start number (nullable): Pagination start index
• limit number (nullable): Maximum results to return
• done boolean (nullable): Filter by done status (true=done, false=undone, null=all)

Returns:

• results array of objects: Activities for the person
  • id number: Activity ID
  • type string (nullable): Activity type
  • subject string (nullable): Activity subject
  • note string (nullable): Activity note
  • done boolean: Whether activity is done
  • dueDate string (nullable): Due date
  • dueTime string (nullable): Due time
  • duration string (nullable): Duration
  • addTime string (nullable): Created timestamp
  • updateTime string (nullable): Updated timestamp
  • markedAsDoneTime string (nullable): When marked as done
• hasMore boolean: Whether more results exist
• nextStart number (nullable): Next pagination start index

Example Usage:

{
  "personId": 12345,
  "done": false,
  "limit": 25
}

Deals

Manage sales deals and opportunities in your Pipedrive CRM pipeline.

Search Deals

Search for deals by title or notes.

Operation Type: Query (Read)

Parameters:

• term string (required): Search term to find deals
• start number (nullable): Pagination start index
• limit number (nullable): Maximum results to return

Returns:

• results array of objects: Matching deals
  • id number: Deal ID
  • title string (nullable): Deal title
  • value number (nullable): Deal value
  • currency string (nullable): Currency
  • status string (nullable): Deal status
  • stageId number (nullable): Stage ID
  • pipelineId number (nullable): Pipeline ID
  • personId number (nullable): Person ID
  • orgId number (nullable): Organization ID
  • addTime string (nullable): Created timestamp
  • updateTime string (nullable): Updated timestamp
• hasMore boolean: Whether more results exist
• nextStart number (nullable): Next pagination start index

Example Usage:

{
  "term": "Enterprise License",
  "limit": 20
}

Get Deal

Retrieve a specific deal by its ID.

Operation Type: Query (Read)

Parameters:

• dealId number (required): The ID of the deal to retrieve

Returns:

• id number: Deal ID
• title string (nullable): Deal title
• value number (nullable): Deal value
• currency string (nullable): Currency
• status string (nullable): Deal status
• stageId number (nullable): Stage ID
• pipelineId number (nullable): Pipeline ID
• personId number (nullable): Person ID
• orgId number (nullable): Organization ID
• ownerId number (nullable): Owner user ID
• expectedCloseDate string (nullable): Expected close date
• wonTime string (nullable): When deal was won
• lostTime string (nullable): When deal was lost
• closeTime string (nullable): When deal was closed
• lostReason string (nullable): Reason for losing
• addTime string (nullable): Created timestamp
• updateTime string (nullable): Updated timestamp

Example Usage:

{
  "dealId": 54321
}

List Deals

Retrieve a paginated list of all deals.

Operation Type: Query (Read)

Parameters:

• start number (nullable): Pagination start index
• limit number (nullable): Maximum results to return

Returns:

• results array of objects: List of deals
• hasMore boolean: Whether more results exist
• nextStart number (nullable): Next pagination start index

Example Usage:

{
  "start": 0,
  "limit": 50
}

Create Deal

Create a new deal in your sales pipeline.

Operation Type: Mutation (Write)

Parameters:

• title string (required): Deal title
• value number (nullable): Deal value
• currency string (nullable): Currency (e.g., USD, EUR)
• personId number (nullable): ID of person to associate with deal
• orgId number (nullable): ID of organization to associate with deal
• stageId number (nullable): ID of stage to place deal in
• status string (nullable): Deal status (open, won, lost)
• expectedCloseDate string (nullable): Expected close date (YYYY-MM-DD)

Returns:

• id number: Created deal ID
• title string (nullable): Deal title
• value number (nullable): Deal value
• currency string (nullable): Currency
• status string (nullable): Deal status
• stageId number (nullable): Stage ID
• pipelineId number (nullable): Pipeline ID
• personId number (nullable): Person ID
• orgId number (nullable): Organization ID
• addTime string (nullable): Created timestamp

Example Usage:

{
  "title": "Enterprise License Agreement",
  "value": 50000,
  "currency": "USD",
  "personId": 12345,
  "stageId": 1,
  "expectedCloseDate": "2024-06-30"
}

Update Deal

Update an existing deal's properties.

Operation Type: Mutation (Write)

Parameters:

• dealId number (required): The ID of the deal to update
• title string (nullable): New title
• value number (nullable): New value
• currency string (nullable): New currency
• personId number (nullable): New person ID
• orgId number (nullable): New organization ID
• stageId number (nullable): New stage ID
• status string (nullable): New status (open, won, lost)
• expectedCloseDate string (nullable): New expected close date
• lostReason string (nullable): Reason for losing (if status is lost)

Returns:

• id number: Deal ID
• title string (nullable): Updated title
• value number (nullable): Updated value
• currency string (nullable): Updated currency
• status string (nullable): Updated status
• stageId number (nullable): Updated stage ID
• pipelineId number (nullable): Pipeline ID
• personId number (nullable): Updated person ID
• orgId number (nullable): Updated organization ID
• updateTime string (nullable): Updated timestamp

Example Usage:

{
  "dealId": 54321,
  "status": "won",
  "value": 75000
}

Notes

Create and manage notes attached to deals, persons, and organizations.

Create Note

Create a new note and attach it to a deal, person, or organization.

Operation Type: Mutation (Write)

Parameters:

• content string (required): Note content
• dealId number (nullable): ID of deal to attach note to
• personId number (nullable): ID of person to attach note to
• orgId number (nullable): ID of organization to attach note to
• pinnedToDealFlag boolean (nullable): Whether to pin note to deal
• pinnedToPersonFlag boolean (nullable): Whether to pin note to person
• pinnedToOrganizationFlag boolean (nullable): Whether to pin note to organization

Returns:

• id number: Created note ID
• content string (nullable): Note content
• dealId number (nullable): Deal ID
• personId number (nullable): Person ID
• orgId number (nullable): Organization ID
• addTime string (nullable): Created timestamp

Example Usage:

{
  "content": "Had a productive call with the customer. They're interested in upgrading to the enterprise plan.",
  "dealId": 54321,
  "pinnedToDealFlag": true
}

List Notes

Retrieve notes with optional filtering by deal, person, or organization.

Operation Type: Query (Read)

Parameters:

• start number (nullable): Pagination start index
• limit number (nullable): Maximum results to return
• dealId number (nullable): Filter by deal ID
• personId number (nullable): Filter by person ID
• orgId number (nullable): Filter by organization ID
• sort string (nullable): Sort field and direction (e.g., "add_time DESC")

Returns:

• results array of objects: List of notes
  • id number: Note ID
  • content string (nullable): Note content
  • dealId number (nullable): Deal ID
  • personId number (nullable): Person ID
  • orgId number (nullable): Organization ID
  • addTime string (nullable): Created timestamp
  • updateTime string (nullable): Updated timestamp
• hasMore boolean: Whether more results exist
• nextStart number (nullable): Next pagination start index

Example Usage:

{
  "dealId": 54321,
  "sort": "add_time DESC",
  "limit": 25
}

Get Note

Retrieve a specific note by its ID.

Operation Type: Query (Read)

Parameters:

• noteId number (required): The ID of the note to retrieve

Returns:

• id number: Note ID
• content string (nullable): Note content
• userId number (nullable): User ID who created note
• dealId number (nullable): Deal ID
• personId number (nullable): Person ID
• orgId number (nullable): Organization ID
• leadId string (nullable): Lead ID
• pinnedToDealFlag boolean: Pinned to deal
• pinnedToPersonFlag boolean: Pinned to person
• pinnedToOrganizationFlag boolean: Pinned to organization
• addTime string (nullable): Created timestamp
• updateTime string (nullable): Updated timestamp

Example Usage:

{
  "noteId": 98765
}

Update Note

Update an existing note's content or pin status.

Operation Type: Mutation (Write)

Parameters:

• noteId number (required): The ID of the note to update
• content string (nullable): New note content
• pinnedToDealFlag boolean (nullable): Whether to pin note to deal
• pinnedToPersonFlag boolean (nullable): Whether to pin note to person
• pinnedToOrganizationFlag boolean (nullable): Whether to pin note to organization

Returns:

• id number: Note ID
• content string (nullable): Updated content
• dealId number (nullable): Deal ID
• personId number (nullable): Person ID
• orgId number (nullable): Organization ID
• updateTime string (nullable): Updated timestamp

Example Usage:

{
  "noteId": 98765,
  "content": "Updated: Customer confirmed they want to proceed with the enterprise plan. Contract sent for review."
}

Pipelines

View sales pipeline configurations for organizing deal progression.

List Pipelines

Retrieve all pipelines in your Pipedrive account.

Operation Type: Query (Read)

Parameters:

• None

Returns:

• results array of objects: List of pipelines
  • id number: Pipeline ID
  • name string: Pipeline name
  • urlTitle string (nullable): URL title
  • orderNr number (nullable): Order number
  • active boolean: Whether pipeline is active
  • dealProbability boolean: Whether deal probability is enabled
  • addTime string (nullable): Created timestamp
  • updateTime string (nullable): Updated timestamp

Example Usage:

{}

Stages

View pipeline stages for tracking deal progression.

List Stages

Retrieve all stages, optionally filtered by pipeline.

Operation Type: Query (Read)

Parameters:

• pipelineId number (nullable): Filter by pipeline ID

Returns:

• results array of objects: List of stages
  • id number: Stage ID
  • name string: Stage name
  • pipelineId number: Pipeline ID
  • orderNr number (nullable): Order number
  • activeFlag boolean: Whether stage is active
  • dealProbability number (nullable): Deal probability percentage
  • rottenFlag boolean: Whether deals can go rotten in this stage
  • rottenDays number (nullable): Days until deal goes rotten
  • addTime string (nullable): Created timestamp
  • updateTime string (nullable): Updated timestamp

Example Usage:

{
  "pipelineId": 1
}

Mail Messages

Access email messages linked to your Pipedrive CRM records.

Get Mail Message

Retrieve a specific mail message by its ID.

Operation Type: Query (Read)

Parameters:

• mailMessageId number (required): The ID of the mail message to retrieve

Returns:

• id number: Mail message ID
• subject string (nullable): Email subject
• snippet string (nullable): Email snippet/preview
• body string (nullable): Email body
• bodyUrl string (nullable): URL to email body
• from array of objects: From addresses
  • email string: Email address
  • name string (nullable): Name
• to array of objects: To addresses
• cc array of objects: CC addresses
• bcc array of objects: BCC addresses
• mailThreadId number (nullable): Mail thread ID
• messageTime string (nullable): Message timestamp
• hasAttachments boolean: Whether has attachments
• read boolean: Whether message is read
• draft string (nullable): Draft status
• dealId number (nullable): Associated deal ID
• personId number (nullable): Associated person ID
• orgId number (nullable): Associated organization ID
• addTime string (nullable): Created timestamp
• updateTime string (nullable): Updated timestamp

Example Usage:

{
  "mailMessageId": 11111
}

Organizations

Access organization (company) records in Pipedrive.

Get Organization

Retrieve a specific organization by its ID.

Operation Type: Query (Read)

Parameters:

• orgId number (required): The ID of the organization to retrieve

Returns:

• id number: Organization ID
• name string (nullable): Organization name
• ownerId number (nullable): Owner user ID
• address string (nullable): Address
• ccEmail string (nullable): CC email address
• activeFlag boolean: Whether organization is active
• addTime string (nullable): Created timestamp
• updateTime string (nullable): Updated timestamp

Example Usage:

{
  "orgId": 99999
}

Common Use Cases

Deal Management:

• Search and filter deals to track pipeline health and identify opportunities
• Create deals with associations to contacts and organizations for complete context
• Update deal stages as opportunities progress through the sales cycle
• Track won/lost deals with reasons to improve sales processes

Contact Intelligence:

• Search persons by email or name to find existing contacts quickly
• Get all activities for a contact before meetings to prepare effectively
• Update contact information as roles or details change
• Link persons to organizations for complete relationship mapping

Activity Tracking:

• Create notes to log meeting outcomes and action items
• Get person activities to understand engagement history
• Track all touchpoints across deals and contacts
• Access email messages linked to CRM records for full communication context

Pipeline Analytics:

• List pipeline stages to understand your sales process structure
• Track deal progression through stages to measure conversion rates
• Monitor stage probabilities to forecast revenue accurately
• Identify rotten deals that need attention based on stage settings