List deals with cursor-based pagination and filtering options. Backed by Pipedrive API v2 (GET /api/v2/deals).

Returns a page of deals. Use filters to narrow results by status, stage, owner, person, organization, or pipeline.

Workflow tips:

• Use status filter to get only 'open', 'won', 'lost', or 'deleted' deals; omit status entirely for all non-deleted deals (v1's 'all_not_deleted' has no v2 equivalent, so it is dropped rather than sent)

• Set owned_by_you=1 to see only your deals (resolves your user id via GET /users/me, cached)

• Combine with filter_id to use pre-configured Pipedrive filters

• Paginate with cursor: pass the cursor from the previous response's additional_data.next_cursor to get the next page; omit it (or pass null) for the first page. A null next_cursor means you're on the last page. 'start' is deprecated and ignored — v2 does not support offset pagination.

• sort_by only accepts a small set of v2 fields (confirmed working: id, add_time, update_time) — arbitrary v1 sort fields like 'title' or 'value' will be rejected by the API

• For all deals without manual pagination, use deals/list_all_auto instead

• Use add_time_from / add_time_until to filter by creation date (client-side). NOTE: this only filters the current page; for complete date-range results use deals/list_all_auto

Common use cases:

• List all open deals: { "status": "open" }

• List my won deals: { "status": "won", "owned_by_you": 1 }

• List deals in a specific stage: { "stage_id": 123 }

• Get the next page: { "cursor": "<next_cursor from previous response>" }

Automatically fetch ALL deals with pagination handling. Backed by Pipedrive API v2 (GET /api/v2/deals), paginated via cursor.

This tool automatically handles cursor pagination and fetches all deals matching the filters. Unlike deals/list, this returns ALL results in a single response.

WARNING: This can return large datasets. Use filters to limit results.

Workflow tips:

• Same filters as deals/list (status, stage_id, user_id, person_id, org_id, etc.)

• Specify max_items to limit total results if needed

• No need to manage cursor - pagination is automatic (loops until additional_data.next_cursor is null)

• Best for exports, reports, or comprehensive analysis

• Use add_time_from / add_time_until to filter by creation date (client-side)

• sort_by only accepts a small set of v2 fields (confirmed working: id, add_time, update_time)

Common use cases:

• Get all open deals: { "status": "open" }

• Export all deals for a pipeline: { "pipeline_id": 1 }

• Get old unqualified deals: { "pipeline_id": 4, "add_time_until": "2023-12-31" }

List archived deals with pagination and filtering options.

Returns a paginated list of archived deals. Archived deals are deals that have been removed from active pipelines.

Workflow tips:

• Use same filters as deals/list (status, stage_id, user_id, person_id, org_id, etc.)

• Filter by user_id to see archived deals by specific user

• Combine with filter_id to use pre-configured Pipedrive filters

• Use start/limit for pagination (default limit: 100, max: 500)

• Useful for historical analysis and cleanup

Common use cases:

• List all archived deals: {}

• List archived deals by user: { "user_id": 123 }

• List archived deals in a specific stage: { "stage_id": 5 }

• List archived deals for a person: { "person_id": 456 }

Create a new deal in Pipedrive.

Creates a new deal with the specified information. Only title is required.

Custom fields:

• Pass display names: { "custom_fields": { "Industria": "Tech", "Budget": 5000 } }

• Or hash keys directly: { "custom_fields": { "abc123...": "raw value" } }

• For enum/set fields, pass option labels (not ids).

Workflow tips:

• Title is the only required field

• Use persons/search or organizations/search to get person_id or org_id

• Use pipelines/list to get pipeline_id and stage_id

• Set expected_close_date in YYYY-MM-DD format

• Probability should be 0-100 (percentage)

• Currency must be a 3-letter code (e.g., USD, EUR, GBP)

Common use cases:

• Simple deal: { "title": "New Deal", "value": 5000, "currency": "USD" }

• Deal with person: { "title": "Deal", "value": 1000, "person_id": 123 }

• Deal with organization: { "title": "Deal", "org_id": 456, "stage_id": 1 }

• Full deal: { "title": "Big Deal", "value": 50000, "currency": "USD", "person_id": 123, "org_id": 456, "pipeline_id": 1, "stage_id": 2, "expected_close_date": "2024-12-31" }

Get detailed information about a specific deal by ID.

Retrieves complete information about a single deal, including all custom fields.

Workflow tips:

• Use deals/search or deals/list to find deal IDs first

• Response includes person, organization, pipeline, and stage information

• Cached for 5 minutes for better performance

Common use cases:

• Get deal details: { "id": 123 }

• Check deal status before updating

• Retrieve deal information for analysis

Update an existing deal.

Updates one or more fields of an existing deal. Only provide fields you want to change.

Custom fields:

• Pass display names: { "id": 123, "custom_fields": { "Industria": "Tech", "Budget": 5000 } }

• Or hash keys directly: { "id": 123, "custom_fields": { "abc123...": "raw value" } }

• For enum/set fields, pass option labels (not ids).

Workflow tips:

• Only specify fields you want to update

• Use deals/get first to see current values

• Use deals/move_to_stage for simple stage changes

• To mark as won/lost, update status field

Common use cases:

• Update value: { "id": 123, "value": 7500 }

• Change title: { "id": 123, "title": "Updated Deal Name" }

• Mark as won: { "id": 123, "status": "won" }

• Update multiple fields: { "id": 123, "value": 10000, "expected_close_date": "2024-12-31", "probability": 75 }

• Move to new stage: { "id": 123, "stage_id": 5 }

Move a deal to a different stage in the pipeline.

Convenience tool to move a deal to another stage. Use this instead of deals/update when only changing stages.

Workflow tips:

• Use pipelines/list to get available stages

• Moving stages may trigger automations in Pipedrive

• Stage must be in the same pipeline or specify pipeline_id

Common use cases:

• Move to next stage: { "id": 123, "stage_id": 5 }

• Move to won/lost stage: { "id": 123, "stage_id": 10 }

Delete a deal permanently.

WARNING: This permanently deletes the deal. Consider marking as lost instead.

Workflow tips:

• Deletion is permanent and cannot be undone

• Consider using deals/update with status='lost' instead

• Use deals/get first to confirm you have the right deal

• Related activities and notes are preserved but detached

Common use cases:

• Delete test deal: { "id": 123 }

• Clean up duplicate: { "id": 456 }

Duplicate an existing deal.

Creates a copy of an existing deal with all its properties. The new deal will have the same values, person, organization, etc.

Workflow tips:

• Creates exact copy except for ID and timestamps

• Followers are NOT copied to the new deal

• Products attached to the deal ARE copied

• Use deals/get to view the original before duplicating

• After duplication, you may want to update the title

Common use cases:

• Duplicate template deal: { "id": 123 }

• Create similar deal: { "id": 456 }

• Workflow: duplicate deal, then update specific fields

Search for deals using a text query.

Searches deals by title, notes, or custom fields. Much faster than filtering all deals.

Workflow tips:

• Search is case-insensitive by default

• Minimum 2 characters for search term

• Use exact_match=true for precise matching

• Combine with person_id or org_id to narrow results

• Use status filter to search only open/won/lost deals

• Results are cached for 5 minutes

Common use cases:

• Search by title: { "term": "acme" }

• Exact match: { "term": "ACME Corp Deal", "exact_match": true }

• Search for person's deals: { "term": "software", "person_id": 123 }

• Search open deals only: { "term": "contract", "status": "open" }

• Search in specific field: { "term": "urgent", "fields": "notes" }

Get deal statistics and summary.

Returns aggregated statistics about deals, including counts by status, total values, and conversion rates.

Workflow tips:

• Useful for dashboards and reporting

• Filter by user_id to see specific user's performance

• Use stage_id to analyze specific pipeline stages

• Combine with filter_id for custom segments

• Results show counts and values by status

Common use cases:

• Overall statistics: {} (no parameters)

• User performance: { "user_id": 123 }

• Stage analysis: { "stage_id": 5 }

• Open deals summary: { "status": "open" }

• Custom filter summary: { "filter_id": 10 }

Get archived deals statistics and summary.

Returns aggregated statistics about archived deals, including counts by status, total values, and conversion rates.

Workflow tips:

• Useful for historical analysis and reporting

• Filter by user_id to see specific user's archived performance

• Use stage_id to analyze archived deals from specific stages

• Combine with filter_id for custom segments

• Results show counts and values by status

Common use cases:

• Overall archived statistics: {} (no parameters)

• User archived performance: { "user_id": 123 }

• Stage archived analysis: { "stage_id": 5 }

• Archived open deals summary: { "status": "open" }

• Custom filter archived summary: { "filter_id": 10 }

Add a follower to a deal.

Followers receive notifications about deal updates and can track the deal's progress.

Workflow tips:

• Use users/list to get user IDs

• User must exist in the Pipedrive account

• Follower receives notifications for deal changes

• Cannot add same follower twice

Common use cases:

• Add team member: { "id": 123, "user_id": 456 }

• Add manager for oversight: { "id": 789, "user_id": 10 }

Remove a follower from a deal.

Stops a user from receiving notifications about this deal.

Workflow tips:

• Use deals/list_followers to get follower IDs first

• Follower ID is different from user ID

• Cannot remove the deal owner

Common use cases:

• Remove follower: { "id": 123, "follower_id": 456 }

• Workflow: list followers, then remove specific one

List all followers of a deal.

Returns list of users following this deal and receiving notifications about it.

Workflow tips:

• Shows user details for each follower

• Includes follower ID needed for removal

• Deal owner is automatically a follower

• Cached for 5 minutes

Common use cases:

• View followers: { "id": 123 }

• Before removing: list to get follower_id

Add a participant (person) to a deal.

Participants are persons who are involved in the deal beyond the primary contact.

Workflow tips:

• Use persons/search to find person IDs

• Person must exist in Pipedrive

• Deal can have multiple participants

• Different from the main person_id on the deal

Common use cases:

• Add decision maker: { "id": 123, "person_id": 456 }

• Add influencer: { "id": 789, "person_id": 101 }

• Add stakeholder: { "id": 234, "person_id": 567 }

Remove a participant from a deal.

Removes a person from the deal's participants list.

Workflow tips:

• Use deals/list_participants to get participant IDs first

• deal_participant_id is NOT the same as person_id

• Cannot remove the primary person (person_id)

Common use cases:

• Remove participant: { "id": 123, "deal_participant_id": 456 }

• Workflow: list participants, then remove by deal_participant_id

List all participants of a deal.

Returns all persons participating in this deal.

Workflow tips:

• Shows person details for each participant

• Includes deal_participant_id needed for removal

• Paginated for deals with many participants

• Cached for 5 minutes

Common use cases:

• View all participants: { "id": 123 }

• Paginated list: { "id": 123, "start": 0, "limit": 50 }

• Before removing: list to get deal_participant_id

Add a product to a deal.

Attaches a product to the deal with specific pricing, quantity, and discount.

Workflow tips:

• Use products/search or products/list to find product IDs

• Product must exist in Pipedrive catalog

• Specify item_price to override default product price

• Quantity defaults to 1 if not specified

• Discount is percentage (0-100)

• Duration is for subscription products

Common use cases:

• Add basic product: { "id": 123, "product_id": 456 }

• With custom price: { "id": 123, "product_id": 456, "item_price": 99.99, "quantity": 2 }

• With discount: { "id": 123, "product_id": 456, "quantity": 10, "discount_percentage": 15 }

• Subscription: { "id": 123, "product_id": 456, "duration": 12, "comments": "Annual subscription" }

Update a product attached to a deal.

Modifies the price, quantity, discount, or other details of a product already attached to a deal.

Workflow tips:

• Use deals/list_products to get product_attachment_id

• product_attachment_id is NOT the same as product_id

• Only specify fields you want to update

• Cannot change the actual product, only its parameters

Common use cases:

• Update quantity: { "id": 123, "product_attachment_id": 789, "quantity": 5 }

• Change price: { "id": 123, "product_attachment_id": 789, "item_price": 149.99 }

• Add discount: { "id": 123, "product_attachment_id": 789, "discount_percentage": 20 }

• Update multiple: { "id": 123, "product_attachment_id": 789, "quantity": 3, "discount_percentage": 10, "comments": "Updated terms" }

Remove a product from a deal.

Detaches a product from the deal.

Workflow tips:

• Use deals/list_products to get product_attachment_id

• product_attachment_id is NOT the same as product_id

• Updates deal value automatically

Common use cases:

• Remove product: { "id": 123, "product_attachment_id": 789 }

• Workflow: list products, then remove by product_attachment_id

List all products attached to a deal.

Returns all products associated with this deal, including pricing and quantity details.

Workflow tips:

• Shows product_attachment_id needed for updates/removal

• Set include_product_data=1 to get full product details

• Includes calculated totals with discounts

• Cached for 5 minutes

Common use cases:

• List products: { "id": 123 }

• With full details: { "id": 123, "include_product_data": 1 }

• Paginated: { "id": 123, "start": 0, "limit": 50 }

Attach a file to a deal.

Uploads and attaches a file to the deal. Useful for contracts, proposals, presentations, etc.

Workflow tips:

• Provide absolute file path on the local system

• File will be uploaded to Pipedrive

• Supports common formats: PDF, DOC, XLS, images, etc.

• File becomes part of the deal's audit trail

Common use cases:

• Attach contract: { "id": 123, "file_path": "/path/to/contract.pdf" }

• Attach proposal: { "id": 456, "file_path": "/path/to/proposal.docx" }

• Attach image: { "id": 789, "file_path": "/path/to/diagram.png" }

List all files attached to a deal.

Returns all files associated with this deal.

Workflow tips:

• Shows file names, sizes, and upload dates

• Includes download URLs for each file

• Paginated for deals with many files

• Cached for 5 minutes

Common use cases:

• List all files: { "id": 123 }

• Paginated list: { "id": 123, "start": 0, "limit": 50 }

• Sorted by date: { "id": 123, "sort": "add_time" }

Get deals timeline grouped by intervals.

Returns open and won deals grouped by a defined interval of time set in a date-type field.

Workflow tips:

• Useful for revenue forecasting and trend analysis

• Group deals by day, week, month, or quarter

• Use field_key to specify which date field to use (e.g., add_time, update_time, close_time, expected_close_date)

• Filter by user, pipeline, or custom filter

• Set exclude_deals to true to get only summary data

• Use totals_convert_currency for multi-currency reporting

Common use cases:

• Monthly revenue forecast: { "start_date": "2024-01-01", "interval": "month", "amount": 12, "field_key": "expected_close_date" }

• Weekly deal creation trends: { "start_date": "2024-01-01", "interval": "week", "amount": 8, "field_key": "add_time" }

• Quarterly sales pipeline: { "start_date": "2024-01-01", "interval": "quarter", "amount": 4, "field_key": "close_time", "pipeline_id": 1 }

• User performance: { "start_date": "2024-01-01", "interval": "month", "amount": 6, "field_key": "won_time", "user_id": 123 }

Get archived deals timeline grouped by intervals.

Returns archived deals grouped by a defined interval of time set in a date-type field.

Workflow tips:

• Analyze historical deal patterns

• Same parameters as deals/get_deals_timeline

• Useful for understanding past performance trends

• Can help identify seasonal patterns

Common use cases:

• Historical analysis: { "start_date": "2023-01-01", "interval": "month", "amount": 12, "field_key": "close_time" }

• Archived deals by quarter: { "start_date": "2023-01-01", "interval": "quarter", "amount": 4, "field_key": "archive_time" }

List all activities associated with a deal.

Returns all activities linked to a specific deal, including calls, meetings, tasks, emails, and deadlines.

Workflow tips:

• Filter by done status to see completed or pending activities

• Use start and limit for pagination

• Exclude specific activity IDs if needed

• Cached for 5 minutes for better performance

• Activities are sorted by due date

Common use cases:

• List all activities: { "id": 123 }

• List pending activities: { "id": 123, "done": "0" }

• List completed activities: { "id": 123, "done": "1" }

• Paginated results: { "id": 123, "start": 0, "limit": 50 }

• Exclude certain activities: { "id": 123, "exclude": "1,2,3" }

List updates about deal field values (changelog).

Returns the complete changelog of a deal, showing all field value changes over time.

Workflow tips:

• See who changed what and when

• Useful for audit trails and compliance

• Shows old and new values for each field

• Includes timestamp and user information

• Cached for 5 minutes

Common use cases:

• View full changelog: { "id": 123 }

• Audit field changes for compliance

• Track who updated deal value or stage

• Understand deal modification history

List updates about a deal (flow).

Returns a chronological list of all updates and activities related to a deal, including field changes, notes, emails, and other events.

Workflow tips:

• Shows complete activity feed for a deal

• Includes field updates, notes, emails, and activities

• Chronologically ordered

• More comprehensive than changelog

• Cached for 5 minutes

Common use cases:

• View deal activity feed: { "id": 123 }

• See all interactions and changes

• Track deal progression timeline

• Review communication history

List updates about participants of a deal.

Returns the changelog of participants added to or removed from a deal.

Workflow tips:

• Track when participants were added/removed

• See who made participant changes

• Useful for team collaboration tracking

• Shows participant modification history

• Cached for 5 minutes

Common use cases:

• View participant history: { "id": 123 }

• Track team involvement over time

• Audit participant changes

• Understand collaboration patterns

List mail messages associated with a deal.

Returns all email messages linked to a specific deal, including sent and received emails.

Workflow tips:

• View email communication history for a deal

• Includes both sent and received messages

• Use pagination for deals with many emails

• Emails are sorted by date (newest first)

• Cached for 5 minutes

• Useful for tracking client communication

Common use cases:

• List all emails: { "id": 123 }

• Paginated results: { "id": 123, "start": 0, "limit": 50 }

• Review email thread for a deal

• Track communication history with client

Merge two deals together.

Merges one deal into another, combining their data. The source deal will be deleted and its data will be merged into the target deal.

Workflow tips:

• The deal specified in 'id' will be DELETED (source)

• The deal specified in 'merge_with_id' will be KEPT (target)

• All activities, notes, and followers will be transferred to the target deal

• Use deals/get to review both deals before merging

• This operation cannot be undone

• Deal products, files, and participants are merged

• Useful for cleaning up duplicates

Common use cases:

• Merge duplicate deals: { "id": 123, "merge_with_id": 456 }

• Consolidate related deals: { "id": 789, "merge_with_id": 456 }

• Clean up data after finding duplicates

Warning: This operation is irreversible. The source deal (id) will be permanently deleted.

List permitted users for a deal.

Returns the list of users who have access to view and edit a specific deal based on its visibility settings.

Workflow tips:

• Shows which users can access the deal

• Depends on deal's visibility settings (private, shared, etc.)

• Includes user details and permission levels

• Useful for access control auditing

• Cached for 5 minutes

Common use cases:

• Check deal access: { "id": 123 }

• Audit who can see a sensitive deal

• Verify team member access

• Review sharing permissions

List all persons associated with a deal.

Returns all persons (contacts) linked to a specific deal, including the primary contact and any participants.

Workflow tips:

• Shows both primary contact and participants

• Includes full person details (name, email, phone, etc.)

• Use pagination for deals with many contacts

• Cached for 5 minutes

• Different from participants (participants are just person references)

Common use cases:

• List all contacts: { "id": 123 }

• Paginated results: { "id": 123, "start": 0, "limit": 50 }

• Get contact information for outreach

• Review all stakeholders in a deal

• Export contact list for communication

Mark a deal as won.

Updates the deal status to "won" and moves it to the appropriate won stage in the pipeline.

Workflow tips:

• Automatically moves deal to won stage

• Updates deal close date to current date

• Triggers won deal notifications and automations

• More convenient than using deals/update with status field

• Use deals/get first to verify the deal details

Common use cases:

• Mark deal as won: { "id": 123 }

• Close successful deals quickly

• Trigger win-based workflows

• Update sales metrics

Mark a deal as lost.

Updates the deal status to "lost" and optionally records the reason why the deal was lost.

Workflow tips:

• Automatically moves deal to lost stage

• Lost reason helps track why deals fail

• Triggers lost deal notifications and automations

• Use for pipeline health and loss analysis

• More convenient than using deals/update with status field

• Lost reason is important for improving sales process

Common use cases:

• Mark deal as lost: { "id": 123 }

• Mark with reason: { "id": 123, "lost_reason": "Competitor pricing" }

• Common lost reasons: "No budget", "Chose competitor", "Timing not right", "No response"

• Track loss patterns for improvement

Delete multiple deals in bulk.

Marks multiple deals as deleted. After 30 days, the deals will be permanently deleted.

Workflow tips:

• Provide an array of deal IDs to delete

• Deals are soft-deleted first (marked as deleted)

• After 30 days, deals are permanently removed

• Use with caution - this affects multiple deals at once

• Consider using deals/list or deals/search to get IDs first

Common use cases:

• Clean up test deals: { "ids": [123, 456, 789] }

• Remove duplicate deals: { "ids": [111, 222] }

• Bulk cleanup after data import

Warning: This operation marks deals as deleted. They can be recovered within 30 days.

Convert a deal into a lead (asynchronous, two-step flow).

Step 1 (this tool): POST starts the conversion. Returns { id: conversion_id, status: 'queued' | 'running' }. Step 2 (separate tool): poll deals_convert_status with the deal id AND the conversion_id returned here, every few seconds, until status === 'completed'. The completed response includes the resulting lead_id.

Related entities (notes, files, emails, activities) are transferred to the new lead.

Check the status of a deal-to-lead conversion job.

Use the conversion_id returned by deals_convert_to_lead. Possible statuses: queued, running, completed, failed. When completed, the response includes the resulting lead_id.

List installments attached to one or more deals (API v2).

Installments are scheduled, fixed payments on a deal (the modern replacement for the legacy subscriptions feature). Pass the deal IDs you want installments for.

Common use cases:

• Installments of one deal: { "deal_ids": [123] }

• Installments across several deals: { "deal_ids": [123, 456, 789] }

Add an installment to a deal (API v2).

Required: description (name), amount (positive, non-zero) and billing_date (YYYY-MM-DD).

Common use cases:

• { "id": 123, "description": "Deposit", "amount": 500, "billing_date": "2026-01-15" }

Update an existing installment on a deal (API v2).

Provide the deal id, the installment_id, and any of description / amount / billing_date.

Delete an installment from a deal (API v2).

List all persons with optional filtering and pagination.

Supports filtering by:

• user_id: Filter by owner

• org_id: Filter by organization

• first_char: Filter by first character of name (single letter)

• filter_id: Apply a saved filter

Returns paginated results. Use start/limit for manual pagination.

Automatically fetch ALL persons using pagination.

This tool handles pagination automatically and returns all persons matching the filters. Use this when you need the complete list without managing pagination manually.

Warning: This can return a large dataset if you have many persons.

Supports the same filters as persons_list:

• user_id: Filter by owner

• org_id: Filter by organization

• first_char: Filter by first character of name

• filter_id: Apply a saved filter

Get all persons using the collection endpoint.

This endpoint provides an alternative way to fetch persons with different capabilities:

• Cursor-based pagination (more efficient for large datasets)

• Date range filtering (since/until)

• Optimized for data synchronization

• Better performance for large-scale operations

Key differences from persons_list:

• Uses cursor pagination instead of offset/limit

• Supports date-based filtering for incremental sync

• More efficient for fetching large volumes

• Better for ETL and data integration scenarios

Parameters:

• cursor: Pagination cursor from previous response

• limit: Items per page (default: 100, max: 500)

• since: Start date (YYYY-MM-DD) - get persons modified since this date

• until: End date (YYYY-MM-DD) - get persons modified until this date

• owner_id: Filter by owner user ID

• first_char: Filter by first character of name

Use cases:

• Initial data synchronization

• Incremental updates (using since parameter)

• Large-scale data exports

• Integration with external systems

• ETL pipelines

• Backup and archival

The cursor-based approach is more reliable than offset pagination for datasets that change frequently, as it maintains consistency even when records are added or deleted during pagination.

Create a new person in Pipedrive.

Required fields:

• name: Full name of the person

Optional fields:

• owner_id: User who will own this person

• org_id: Organization this person belongs to

• email: Array of email addresses with format: [{"value": "john@company.com", "primary": true, "label": "work"}]

• phone: Array of phone numbers with format: [{"value": "+1234567890", "primary": true, "label": "mobile"}]

• job_title: Job title / function of the person (max 255 characters)

• visible_to: Visibility level (1=owner only, 3=entire company, 5=owner's followers, 7=visibility group)

• marketing_status: Marketing consent status (no_consent, unsubscribed, subscribed, archived)

• add_time: Optional creation time in YYYY-MM-DD HH:MM:SS format

Example email/phone arrays: { "email": [ {"value": "john@company.com", "primary": true, "label": "work"}, {"value": "john@personal.com", "primary": false, "label": "home"} ], "phone": [ {"value": "+1234567890", "primary": true, "label": "mobile"} ] }

Custom fields:

• Pass display names: { "custom_fields": { "Region": "EU", "Tier": "Gold" } }

• Or hash keys directly: { "custom_fields": { "abc123...": "raw value" } }

• For enum/set fields, pass option labels (not ids).

Get detailed information about a specific person by ID.

Returns all person data including:

• Basic info (name, owner, organization)

• Contact details (emails, phones)

• Visibility and marketing status

• Activity counts (deals, activities, files, etc.)

• Timeline info (next activity, last activity)

• Custom fields

Update an existing person's information.

Required fields:

• id: Person ID to update

Optional fields (only provide fields you want to change):

• name: Full name

• owner_id: User who will own this person

• org_id: Organization this person belongs to

• email: Array of email addresses with format: [{"value": "john@company.com", "primary": true, "label": "work"}]

• phone: Array of phone numbers with format: [{"value": "+1234567890", "primary": true, "label": "mobile"}]

• job_title: Job title / function of the person (max 255 characters)

• visible_to: Visibility level (1=owner only, 3=entire company, 5=owner's followers, 7=visibility group)

• marketing_status: Marketing consent status (no_consent, unsubscribed, subscribed, archived)

Note: When updating email/phone arrays, provide the complete array (it replaces the existing one).

Custom fields:

• Pass display names: { "custom_fields": { "Region": "EU", "Tier": "Gold" } }

• Or hash keys directly: { "custom_fields": { "abc123...": "raw value" } }

• For enum/set fields, pass option labels (not ids).

Delete a person from Pipedrive.

Warning: This action cannot be undone. The person will be permanently deleted.

Note: Deleting a person does not automatically delete associated:

• Deals (they will remain but without the person link)

• Activities (they will remain but without the person link)

• Notes (they will remain but without the person link)

Delete multiple persons in bulk.

Efficiently deletes multiple person records in a single operation. This is useful for:

• Data cleanup and maintenance

• Removing duplicate records

• Batch operations after data imports

• CRM hygiene improvements

• GDPR and data retention compliance

WARNING: This action is irreversible. All specified persons will be permanently deleted, including:

• Person data and custom fields

• Associated notes (if configured)

• Follow relationships

• Activity history (may be preserved depending on settings)

Best practices:

1. Always verify the IDs before deletion

2. Consider exporting data as backup

3. Check if persons have active deals

4. Review organization associations

5. Ensure you have proper permissions

The 'ids' parameter should be a comma-separated string of person IDs. Example: "123,456,789" will delete persons with IDs 123, 456, and 789.

Rate limits may apply for very large deletions. Consider batching if deleting hundreds or thousands of records.

Search for persons by name, email, phone, or notes.

The search uses Pipedrive's intelligent search that:

• Searches across multiple fields (name, email, phone, notes, custom fields)

• Supports fuzzy matching by default

• Returns ranked results

Search options:

• term: Search term (minimum 2 characters)

• fields: Specific fields to search in (default: all fields)

• exact_match: Use exact matching instead of fuzzy search

• org_id: Filter results by organization

• include_fields: Additional fields to include in response

The search is case-insensitive and supports partial matches.

List all deals associated with a specific person.

Returns all deals where the person is linked, including:

• Deal details (title, value, stage, status)

• Timeline information

• Owner information

• Organization information

Filters:

• status: Filter by deal status (open, won, lost, deleted, all_not_deleted)

• sort: Sort by specific field

Supports pagination for large result sets.

List all activities associated with a specific person.

Returns all activities (calls, meetings, tasks, etc.) linked to the person, including:

• Activity details (type, subject, description)

• Due date and time

• Completion status

• Owner/assignee information

• Related deal/organization

Filters:

• done: Filter by completion status (true=completed, false=pending)

Supports pagination for large result sets.

List all files attached to a specific person.

Returns all files associated with the person, including:

• File metadata (name, type, size)

• Upload information (uploader, timestamps)

• File URL for download

• Associated deal/organization if applicable

Supports:

• Pagination for large file lists

• Sorting by various fields

This includes files uploaded directly to the person and files from related deals/activities.

List products associated with a person.

Returns all products that have been sold to or associated with this person through deals. This provides an overview of:

• All products the person has purchased

• Products in active deals

• Historical product associations

• Product preferences and patterns

Each entry includes:

• Product details (name, code, price)

• Deal information

• Quantities and pricing

• Dates and status

• Custom product fields

This is useful for:

• Understanding customer purchase history

• Cross-selling and upselling opportunities

• Product preferences analysis

• Revenue tracking per person

• Customer success and account management

• Renewal and subscription management

The data is aggregated from all deals associated with the person.

List mail messages associated with a person.

Returns all email messages linked to this person, including:

• Emails sent to the person

• Emails received from the person

• Email threads and conversations

• Message subjects and snippets

• Send/receive timestamps

• Associated deals or organizations

This is useful for:

• Reviewing email communication history

• Understanding customer interactions

• Preparing for meetings or calls

• Tracking email engagement

• CRM integration and context

Supports pagination for handling large email histories.

Add a follower to a person.

Followers are users who will receive notifications about updates to this person. This is useful for team collaboration and keeping stakeholders informed.

When a user follows a person, they will be notified about:

• Changes to person details

• New activities

• New deals

• New notes

• Other updates

Note: Users can only be added as followers if they have access to the person.

List all followers of a specific person.

Returns a list of users who are following this person and will receive notifications about updates.

Each follower entry includes:

• User ID

• User name

• User email

• When they started following

This is useful for:

• Checking who is tracking a person

• Auditing team access

• Managing notifications

Delete a follower from a person.

Removes a user from the list of followers for this person. After removal:

• The user will no longer receive notifications about person updates

• They will still have access to the person if permissions allow

• This only affects notification settings, not access rights

This is useful for:

• Managing notification preferences

• Adjusting team involvement

• Reducing notification noise

• Changing account ownership responsibilities

Note: The follower_id is the user ID of the follower to remove.

List updates about person field values (changelog).

Returns a chronological list of changes made to person fields. This is useful for:

• Auditing field changes

• Tracking data modifications

• Understanding update history

• Compliance and reporting

The changelog shows:

• Which fields were changed

• Old and new values

• Who made the change

• When the change occurred

Uses cursor-based pagination for efficient navigation through large change histories.

List updates about a person (activity stream).

Returns a comprehensive timeline of all activities and changes related to a person:

• Field changes and updates

• Activities (calls, meetings, emails)

• Notes added

• Deals created or updated

• Files attached

• Followers added

• Other related events

This provides a complete audit trail and activity history for the person.

Parameters:

• all_changes: Set to show all field changes (not just recent)

• items: Filter which types of items to include in the stream

Useful for:

• Getting a complete overview of interactions

• Understanding person engagement history

• Tracking relationship development

• Customer success and account management

Merge two persons into one.

Combines two person records, moving all related data to the primary person:

• All deals are transferred

• All activities are transferred

• All notes are transferred

• All files are transferred

• Email and phone numbers are combined

• Custom field data is merged

• The secondary person is deleted

WARNING: This action is irreversible. The person specified in merge_with_id will be deleted permanently.

Best practices:

1. Review both persons thoroughly before merging

2. Ensure you're merging duplicates, not different people

3. The person with ID 'id' will be kept (primary)

4. The person with 'merge_with_id' will be deleted (secondary)

5. Use persons_get to verify both records first

Use cases:

• Removing duplicate persons

• Consolidating split records

• Data cleanup and maintenance

• CRM hygiene improvements

List users permitted to access a person.

Returns a list of all users who have permission to view and/or edit this person record. This is determined by:

• The person's visibility settings

• User roles and permissions

• Team assignments

• Sharing rules

Each entry includes:

• User ID

• User name and email

• Access level (view/edit)

• Permission source

This is useful for:

• Security auditing

• Access management

• Understanding data visibility

• Compliance and governance

• Team coordination

Note: Results depend on the visibility settings of the person (e.g., owner only, owner's team, everyone, etc.).

Add or update a person's profile picture.

Uploads an image file to set as the person's profile picture. The image will be:

• Displayed in person records

• Shown in lists and search results

• Visible to users with access to the person

• Used across the Pipedrive interface

Image requirements:

• Format: JPEG, PNG, GIF

• Recommended size: 512x512 pixels

• Maximum file size: Typically 5-10 MB (check Pipedrive limits)

Cropping parameters (optional):

• Use crop_x, crop_y to set the top-left corner of the crop area

• Use crop_width, crop_height to define the crop dimensions

• All crop values are in pixels

• If not provided, the full image is used

Workflow:

1. Read the image file as a Buffer

2. Provide the filename (with extension)

3. Optionally specify crop parameters

4. The tool uploads and sets the picture

Use cases:

• Adding profile photos for contacts

• Updating person images

• Visual identification in CRM

• Personalization and branding

Delete a person's profile picture.

Removes the profile picture from the person record. The person will revert to:

• Default avatar

• Or initials-based placeholder

• Depending on Pipedrive settings

This is useful for:

• Updating outdated photos

• Privacy compliance (GDPR, etc.)

• Data cleanup

• Resetting profile images

Note: This does not delete the image file from Pipedrive storage, it only removes the association with the person.

List organizations with pagination support. Returns paginated list of organizations with filtering options.

Automatically fetch all organizations across all pages. Use this when you need complete data without manual pagination.

Create a new organization. Name is required. Supports address fields and custom fields.

Custom fields:

• Pass display names: { "custom_fields": { "Industry": "Tech", "Tier": "Gold" } }

• Or hash keys directly: { "custom_fields": { "abc123...": "raw value" } }

• For enum/set fields, pass option labels (not ids).

Get details of a specific organization by ID.

Update an existing organization. Only provided fields will be updated.

Custom fields:

• Pass display names: { "custom_fields": { "Industry": "Tech", "Tier": "Gold" } }

• Or hash keys directly: { "custom_fields": { "abc123...": "raw value" } }

• For enum/set fields, pass option labels (not ids).

Delete an organization by ID.

Search organizations by name or other fields. Returns matching organizations.

List all persons associated with a specific organization.

List all deals associated with a specific organization.

List all activities associated with a specific organization.

List all files attached to a specific organization.

Add a follower to an organization.

List all followers of a specific organization.

Returns the users that are following this organization and will receive notifications about updates.

Each follower entry includes:

• User ID

• User name

• User email

• When they started following

This is useful for:

• Checking who is tracking an organization

• Auditing team access

• Managing notifications

Delete multiple organizations in bulk.

Efficiently deletes multiple organization records in a single operation. This is useful for:

• Data cleanup and maintenance

• Removing duplicate records

• Batch operations after data imports

• CRM hygiene improvements

• GDPR and data retention compliance

WARNING: This action is irreversible. All specified organizations will be permanently deleted, including:

• Organization data and custom fields

• Associated notes (if configured)

• Follow relationships

• Activity history (may be preserved depending on settings)

Best practices:

1. Always verify the IDs before deletion

2. Consider exporting data as backup

3. Check if organizations have active deals

4. Review person associations

5. Ensure you have proper permissions

The 'ids' parameter should be a comma-separated string of organization IDs. Example: "123,456,789" will delete organizations with IDs 123, 456, and 789.

Rate limits may apply for very large deletions. Consider batching if deleting hundreds or thousands of records.

Get all organizations using the collection endpoint.

This endpoint provides an alternative way to fetch organizations with different capabilities:

• Cursor-based pagination (more efficient for large datasets)

• Date range filtering (since/until)

• Optimized for data synchronization

• Better performance for large-scale operations

Key differences from organizations/list:

• Uses cursor pagination instead of offset/limit

• Supports date-based filtering for incremental sync

• More efficient for fetching large volumes

• Better for ETL and data integration scenarios

Parameters:

• cursor: Pagination cursor from previous response

• limit: Items per page (default: 100, max: 500)

• since: Start date (YYYY-MM-DD) - get organizations modified since this date

• until: End date (YYYY-MM-DD) - get organizations modified until this date

• owner_id: Filter by owner user ID

• first_char: Filter by first character of name

Use cases:

• Initial data synchronization

• Incremental updates (using since parameter)

• Large-scale data exports

• Integration with external systems

• ETL pipelines

• Backup and archival

The cursor-based approach is more reliable than offset pagination for datasets that change frequently, as it maintains consistency even when records are added or deleted during pagination.

List updates about organization field values (changelog).

Returns a chronological list of changes made to organization fields. This is useful for:

• Auditing field changes

• Tracking data modifications

• Understanding update history

• Compliance and reporting

The changelog shows:

• Which fields were changed

• Old and new values

• Who made the change

• When the change occurred

Uses cursor-based pagination for efficient navigation through large change histories.

List updates about an organization (activity stream).

Returns a comprehensive timeline of all activities and changes related to an organization:

• Field changes and updates

• Activities (calls, meetings, emails)

• Notes added

• Deals created or updated

• Files attached

• Followers added

• Other related events

This provides a complete audit trail and activity history for the organization.

Parameters:

• all_changes: Set to show all field changes (not just recent)

• items: Filter which types of items to include in the stream

Useful for:

• Getting a complete overview of interactions

• Understanding organization engagement history

• Tracking relationship development

• Account management and customer success

Delete a follower from an organization.

Removes a user from the list of followers for this organization. After removal:

• The user will no longer receive notifications about organization updates

• They will still have access to the organization if permissions allow

• This only affects notification settings, not access rights

This is useful for:

• Managing notification preferences

• Adjusting team involvement

• Reducing notification noise

• Changing account ownership responsibilities

Note: The follower_id is the user ID of the follower to remove.

List mail messages associated with an organization.

Returns all email messages linked to this organization, including:

• Emails sent to the organization

• Emails received from the organization

• Email threads and conversations

• Message subjects and snippets

• Send/receive timestamps

• Associated deals or persons

This is useful for:

• Reviewing email communication history

• Understanding customer interactions

• Preparing for meetings or calls

• Tracking email engagement

• CRM integration and context

Supports pagination for handling large email histories.

Merge two organizations into one.

Combines two organization records, moving all related data to the primary organization:

• All deals are transferred

• All activities are transferred

• All notes are transferred

• All files are transferred

• All persons are transferred

• Custom field data is merged

• The secondary organization is deleted

WARNING: This action is irreversible. The organization specified in merge_with_id will be deleted permanently.

Best practices:

1. Review both organizations thoroughly before merging

2. Ensure you're merging duplicates, not different organizations

3. The organization with ID 'id' will be kept (primary)

4. The organization with 'merge_with_id' will be deleted (secondary)

5. Use organizations/get to verify both records first

Use cases:

• Removing duplicate organizations

• Consolidating split records

• Data cleanup and maintenance

• CRM hygiene improvements

List users permitted to access an organization.

Returns a list of all users who have permission to view and/or edit this organization record. This is determined by:

• The organization's visibility settings

• User roles and permissions

• Team assignments

• Sharing rules

Each entry includes:

• User ID

• User name and email

• Access level (view/edit)

• Permission source

This is useful for:

• Security auditing

• Access management

• Understanding data visibility

• Compliance and governance

• Team coordination

Note: Results depend on the visibility settings of the organization (e.g., owner only, owner's team, everyone, etc.).

List activities with pagination and filtering options. Can filter by user, type, done status, and date range.

Automatically fetch all activities across all pages. Use this when you need complete data without manual pagination.

Create a new activity. Subject, type, and due_date are required. Can link to deals, persons, organizations, projects, or leads.

Get details of a specific activity by ID.

Update an existing activity. Only provided fields will be updated.

Delete an activity by ID.

Delete multiple activities in a single request.

This endpoint allows you to delete up to 100 activities at once by providing an array of activity IDs.

Workflow tips:

• Maximum 100 activities per request

• All activities must exist and be accessible to the user

• Deletion is permanent and cannot be undone

• Failed deletions for individual activities won't stop others from being deleted

Common use cases:

• Clean up completed activities in bulk

• Remove outdated or duplicate activities

• Archive old activities by deleting them

Example: { "ids": [123, 456, 789] }

Mark an activity as done. This is a convenience tool that updates the activity with done: true.

List all activities associated with a specific deal.

Upload a file to Pipedrive and attach it to a deal, person, organization, activity, or product.

Uploads a file from the specified file path and associates it with at least one entity.

Workflow tips:

• Provide the full file path to upload

• At least one entity ID must be provided (deal_id, person_id, org_id, activity_id, or product_id)

• The file name will be extracted from the path automatically

• Supports all common file types (documents, images, videos, etc.)

• Maximum file size depends on your Pipedrive plan

Common use cases:

• Attach contract to deal: { "file_path": "/path/contract.pdf", "deal_id": 123 }

• Add profile photo to person: { "file_path": "/path/photo.jpg", "person_id": 456 }

• Upload document to organization: { "file_path": "/path/doc.docx", "org_id": 789 }

• Attach multiple entities: { "file_path": "/path/file.pdf", "deal_id": 123, "person_id": 456 }

List files with pagination and filtering options.

Returns a paginated list of files. Use filters to narrow results by associated entity (deal, person, organization, activity, product).

Workflow tips:

• Filter by entity to get files for specific deals, persons, organizations, etc.

• Use sort to order by add_time, update_time, file_name, or file_size

• Set include_deleted_files=true to see deleted files

• Use start/limit for pagination (default limit: 100, max: 500)

• Combine multiple filters to narrow results

Common use cases:

• List all files for a deal: { "deal_id": 123 }

• List all files for a person: { "person_id": 456 }

• List all files for an organization: { "org_id": 789 }

• List recent files sorted by upload time: { "sort": "add_time", "sort_by": "desc" }

Get detailed information about a specific file.

Returns file metadata including name, size, type, associated entities, upload date, and more.

Workflow tips:

• Use this to get file metadata before downloading

• Returns information about which entities (deals, persons, orgs) the file is attached to

• Includes file type, size, and MIME type

• Shows who uploaded the file and when

Common use cases:

• Get file details: { "id": 123 }

• Check file associations before modifying

• Verify file exists before downloading

Get download URL for a file.

Returns a temporary download URL that can be used to download the file content.

Workflow tips:

• Returns a URL that expires after a certain time

• Use the URL to download the actual file content

• The URL includes authentication, so no additional headers needed

• Best used immediately after retrieval

Common use cases:

• Get download link: { "id": 123 }

• Download file for processing or backup

• Share temporary access to a file

Update file metadata (name or description).

Updates a file's name or description. Does not modify the actual file content.

Workflow tips:

• Can update file name (without extension) or description

• Name must not exceed 255 characters

• Description limited to 1000 characters

• At least one field (name or description) should be provided

Common use cases:

• Rename file: { "id": 123, "name": "Updated Contract" }

• Add description: { "id": 123, "description": "Q4 2024 sales contract" }

• Update both: { "id": 123, "name": "Contract V2", "description": "Updated terms" }

Delete a file from Pipedrive.

Permanently removes a file and its associations with entities.

Workflow tips:

• Deleting a file removes it from all associated entities

• This action cannot be undone

• Consider using files_get first to verify the file

• Deleted files may still appear in lists if include_deleted_files=true

Common use cases:

• Remove file: { "id": 123 }

• Clean up old attachments

• Remove duplicate files

Link a remote file from Google Drive, Dropbox, OneDrive, Box, or SharePoint.

Creates a link to a file stored in external cloud storage and associates it with a Pipedrive entity.

Workflow tips:

• Supported platforms: googledrive, dropbox, onedrive, box, sharepoint

• Provide the remote file's ID from the cloud storage platform

• Specify which entity type and ID to link to

• Remote files appear alongside uploaded files in Pipedrive

Common use cases:

• Link Google Drive file to deal: { "item_type": "deal", "item_id": 123, "remote_id": "1a2b3c", "remote_location": "googledrive" }

• Link Dropbox file to person: { "item_type": "person", "item_id": 456, "remote_id": "xyz789", "remote_location": "dropbox" }

• Link OneDrive file to org: { "item_type": "organization", "item_id": 789, "remote_id": "abc123", "remote_location": "onedrive" }

Search across all Pipedrive entities (deals, persons, organizations, products, leads, files).

Performs a universal search that can search across multiple item types simultaneously.

Workflow tips:

• Search term must be at least 2 characters (1 if exact_match is true)

• Specify item_types to limit search to specific entities

• Use exact_match=true for precise searches

• search_for_related_items=true includes up to 100 related items

• Results include result_score for relevance ranking

• Can search specific fields using the fields parameter

Common use cases:

• Search everything: { "term": "acme" }

• Search deals only: { "term": "contract", "item_types": ["deal"] }

• Search persons and orgs: { "term": "john", "item_types": ["person", "organization"] }

• Exact match search: { "term": "John Smith", "exact_match": true }

• Search specific fields: { "term": "email@example.com", "fields": "email,phone" }

Search for items by a specific field value.

Searches for items by targeting a specific field (custom or standard fields).

Workflow tips:

• Specify field_type: dealField, personField, organizationField, or productField

• Provide field_key: the API key of the field to search

• Use exact_match=true for precise matches

• return_item_ids=true returns only IDs instead of full objects

• Useful for searching custom fields

Common use cases:

• Search deal by custom field: { "term": "ABC123", "field_type": "dealField", "field_key": "custom_id" }

• Search person by email: { "term": "john@example.com", "field_type": "personField", "field_key": "email" }

• Search org by domain: { "term": "acme.com", "field_type": "organizationField", "field_key": "domain" }

• Get IDs only: { "term": "value", "field_type": "dealField", "field_key": "field", "return_item_ids": true }

Search for deals with advanced filtering options.

Performs a deal-specific search with additional filtering by person, organization, and status.

Workflow tips:

• Search term must be at least 2 characters

• Filter by person_id, org_id to narrow results

• Filter by status: open, won, lost, all_not_deleted

• Specify fields to search: title, notes, custom fields

• Use include_fields to limit response data

• Results ordered by relevance

Common use cases:

• Search deals by title: { "term": "contract" }

• Search open deals: { "term": "acme", "status": "open" }

• Search deals for person: { "term": "proposal", "person_id": 123 }

• Search specific fields: { "term": "urgent", "fields": "title,notes" }

• Limit response data: { "term": "deal", "include_fields": "title,value,stage_id" }

Search for persons with advanced filtering options.

Performs a person-specific search with additional filtering by organization.

Workflow tips:

• Search term must be at least 2 characters

• Filter by org_id to find persons in specific organizations

• Specify fields to search: name, email, phone, custom fields

• Use include_fields to limit response data

• Use exact_match for precise searches

• Results ordered by relevance

Common use cases:

• Search by name: { "term": "john smith" }

• Search by email: { "term": "john@example.com", "fields": "email" }

• Search in organization: { "term": "smith", "org_id": 123 }

• Search phone numbers: { "term": "+1234567890", "fields": "phone" }

• Limit response: { "term": "john", "include_fields": "name,email,phone" }

Search for organizations with advanced filtering options.

Performs an organization-specific search across all organization fields.

Workflow tips:

• Search term must be at least 2 characters

• Specify fields to search: name, address, custom fields

• Use include_fields to limit response data

• Use exact_match for precise searches

• Results ordered by relevance

• Useful for finding companies by name or domain

Common use cases:

• Search by name: { "term": "acme corporation" }

• Search by address: { "term": "new york", "fields": "address" }

• Exact company match: { "term": "ACME Corp", "exact_match": true }

• Search custom field: { "term": "enterprise", "fields": "customer_type" }

• Limit response: { "term": "acme", "include_fields": "name,address,owner_id" }

Search for products with advanced filtering options.

Performs a product-specific search across all product fields.

Workflow tips:

• Search term must be at least 2 characters

• Specify fields to search: name, code, description, custom fields

• Use include_fields to limit response data

• Use exact_match for precise searches (e.g., SKU lookup)

• Results ordered by relevance

• Useful for finding products by name, code, or SKU

Common use cases:

• Search by name: { "term": "premium subscription" }

• Search by code/SKU: { "term": "SKU-123", "fields": "code" }

• Exact product match: { "term": "PRD-001", "exact_match": true }

• Search description: { "term": "enterprise", "fields": "description" }

• Limit response: { "term": "product", "include_fields": "name,code,price" }

List all pipelines.

Returns all pipelines in the Pipedrive account, including their stages.

Workflow tips:

• Returns both active and inactive pipelines

• Each pipeline includes its stages

• Use this to get pipeline IDs for deal creation

• Check deal_probability setting to see if probability tracking is enabled

• order_nr indicates the display order in Pipedrive

Common use cases:

• Get all pipelines: {}

• Find pipeline ID for deal creation

• Check available stages in each pipeline

• Verify pipeline configuration

Get detailed information about a specific pipeline.

Returns pipeline details including all its stages and deal statistics.

Workflow tips:

• Returns pipeline configuration and all stages

• Includes deal totals and conversion statistics

• Use totals_convert_currency to convert deal values to specific currency

• Shows stage order and probabilities

• Includes rotten deal settings per stage

Common use cases:

• Get pipeline details: { "id": 1 }

• Get pipeline with USD totals: { "id": 1, "totals_convert_currency": "USD" }

• Check stage configuration

• Analyze pipeline performance

Create a new pipeline.

Creates a new pipeline with the specified name and configuration.

Workflow tips:

• Only name is required

• Set order_nr to control display order (lower numbers first)

• active=false to create inactive pipeline

• deal_probability=true enables probability tracking (default)

• New pipelines start with no stages - add stages separately

Common use cases:

• Simple pipeline: { "name": "Sales Pipeline" }

• Inactive pipeline: { "name": "Archive", "active": false }

• Ordered pipeline: { "name": "Q1 Pipeline", "order_nr": 1 }

• Full config: { "name": "Enterprise Sales", "order_nr": 2, "active": true, "deal_probability": true }

Update an existing pipeline.

Updates pipeline configuration including name, order, active status, and probability tracking.

Workflow tips:

• All fields except id are optional

• Use order_nr to reorder pipelines

• Set active=false to deactivate pipeline

• Changing deal_probability affects all stages

• At least one field should be updated

Common use cases:

• Rename pipeline: { "id": 1, "name": "New Sales Pipeline" }

• Deactivate pipeline: { "id": 1, "active": false }

• Reorder pipeline: { "id": 1, "order_nr": 5 }

• Update multiple fields: { "id": 1, "name": "Updated", "active": true, "order_nr": 1 }

Delete a pipeline.

Permanently removes a pipeline and all its stages.

Workflow tips:

• This action cannot be undone

• Deals in this pipeline will need to be moved first

• Consider deactivating instead of deleting

• All stages in the pipeline will be deleted

• Use pipelines_get first to verify

Common use cases:

• Remove pipeline: { "id": 1 }

• Clean up unused pipelines

• Remove test pipelines

Get all stages for a specific pipeline.

Returns all stages in a pipeline with their configuration.

Workflow tips:

• Returns stages in order (by order_nr)

• Shows deal probability for each stage

• Includes rotten deal settings

• Use this to get stage IDs for deal creation

Common use cases:

• Get stages: { "id": 1 }

• Find stage ID for deal placement

• Check stage probabilities

• Review stage order

Create a new pipeline stage.

Required: name + pipeline_id. Optional: order_nr (position in pipeline), deal_probability (0-100), is_deal_rot_enabled + days_to_rot for rotting deals.

Common use cases:

• Basic stage: { "name": "Qualified", "pipeline_id": 1 }

• With probability and rot: { "name": "Negotiation", "pipeline_id": 1, "deal_probability": 75, "is_deal_rot_enabled": true, "days_to_rot": 30 }

Update an existing stage.

Provide only the fields you want to change. To reorder stages within a pipeline, update the order_nr field.

Common use cases:

• Rename: { "id": 5, "name": "Closed Won" }

• Reorder: { "id": 5, "order_nr": 0 }

• Adjust rot rules: { "id": 5, "is_deal_rot_enabled": true, "days_to_rot": 14 }

Get all stages across all pipelines or filter by pipeline.

Returns data about all stages with their configuration.

Workflow tips:

• Omit pipeline_id to get stages from all pipelines

• Use pipeline_id to filter stages for a specific pipeline

• Returns stages with order, probability, and rotten settings

• Shows which pipeline each stage belongs to

• Results include pagination info

Common use cases:

• Get all stages: {}

• Get all stages: { "pipeline_id": null }

• Filter by pipeline: { "pipeline_id": 1 }

• Review all stage configurations across pipelines

• Find stage IDs for deal management

Get a specific stage by ID.

Returns the stage's full configuration: name, pipeline_id, order_nr, probability, rotting settings.

Delete a stage by ID.

This is a soft delete. Existing deals in the stage are NOT cascaded — they remain pointing to the deleted stage's ID until they are moved.

Delete multiple stages in bulk.

Marks multiple stages as deleted in one operation.

Note: This endpoint has been deprecated by Pipedrive. Consider using stages_delete for each stage instead.

Workflow tips:

• Provide comma-separated stage IDs

• All specified stages will be deleted

• Deletion is irreversible

• Consider impact on deals in these stages

• Returns array of deleted stage IDs

Common use cases:

• Delete multiple stages: { "ids": "1,2,3" }

• Bulk cleanup of unused stages

• Remove multiple deprecated stages

• Pipeline reorganization

Get deal conversion rates in a pipeline for a specific time period.

Returns stage-to-stage conversion rates and pipeline-to-close rates, showing how deals progress through the pipeline.

Response includes:

• stage_conversions: Array of conversion rates between stages

• won_conversion: Rate of deals won

• lost_conversion: Rate of deals lost

Workflow tips:

• Requires start_date and end_date in YYYY-MM-DD format

• Defaults to authorized user unless user_id is specified

• Use to analyze pipeline efficiency and identify bottlenecks

• Track conversion improvements over time

• Compare different time periods or users

Common use cases:

• Get Q4 2023 conversions: { "id": 1, "start_date": "2023-10-01", "end_date": "2023-12-31" }

• Track specific user performance: { "id": 1, "start_date": "2023-01-01", "end_date": "2023-12-31", "user_id": 123 }

• Identify weak conversion points in pipeline

• Monitor sales team effectiveness

Get deal movement statistics in a pipeline for a specific time period.

Returns comprehensive statistics about how deals moved through the pipeline, including new deals, won/lost deals, and average deal age.

Response includes:

• movements_between_stages: Count of stage transitions

• new_deals: Count, IDs, values of new deals created

• deals_left_open: Deals still in pipeline

• won_deals: Successfully closed deals

• lost_deals: Lost opportunities

• average_age_in_days: Deal duration metrics by stage

Workflow tips:

• Requires start_date and end_date in YYYY-MM-DD format

• Defaults to authorized user unless user_id is specified

• Values returned in multiple currencies

• Use to understand pipeline velocity and deal flow

• Track deal aging and identify stalled deals

Common use cases:

• Monthly pipeline report: { "id": 1, "start_date": "2023-10-01", "end_date": "2023-10-31" }

• Track team member activity: { "id": 1, "start_date": "2023-01-01", "end_date": "2023-12-31", "user_id": 123 }

• Analyze deal flow patterns

• Monitor sales cycle length

• Identify pipeline bottlenecks

Get all deals in a specific pipeline.

Returns a list of deals in the pipeline with optional filtering by stage, user, or custom filter. Includes pagination support and optional summary statistics.

Workflow tips:

• Filter by stage_id to see deals in specific stage

• Use everyone=1 to see all deals (ignores filter_id and user_id)

• Set get_summary=1 to include pipeline totals in additional_data

• Use totals_convert_currency to convert values to specific currency

• Supports pagination with start and limit parameters

• Can apply custom filters with filter_id

Common use cases:

• Get all deals in pipeline: { "id": 1 }

• Get deals in specific stage: { "id": 1, "stage_id": 5 }

• Get deals for user: { "id": 1, "user_id": 123 }

• Get everyone's deals with summary: { "id": 1, "everyone": 1, "get_summary": 1 }

• Paginated results: { "id": 1, "start": 0, "limit": 50 }

• Convert to USD: { "id": 1, "totals_convert_currency": "USD", "get_summary": 1 }

List all pipeline stages across the workspace.

Optionally filter by pipeline_id to scope to a single pipeline. Returns the canonical stage collection via API v2.

Cached for 5 minutes.

Common use cases:

• List all stages: {}

• List stages of a pipeline: { "pipeline_id": 3 }

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

Creates a note with the specified content and associates it with one or more entities.

Workflow tips:

• content is required and supports HTML formatting

• At least one entity should be specified (implicitly via schemas)

• Set pinned flags to pin note to specific entities

• user_id sets the note creator (defaults to authenticated user)

• add_time can be specified for backdating notes

• Content supports rich text and can include formatting

Common use cases:

• Simple note: { "content": "Follow up next week", "deal_id": 123 }

• Pinned note: { "content": "Important info", "person_id": 456, "pinned_to_person_flag": true }

• Multi-entity note: { "content": "Meeting notes", "deal_id": 123, "person_id": 456 }

• Rich text note: { "content": "Action items:Send proposal", "deal_id": 789 }

List notes with pagination and filtering options.

Returns a paginated list of notes. Use filters to narrow results by associated entity.

Workflow tips:

• Filter by entity to get notes for specific deals, persons, organizations, or leads

• Filter by user_id to get notes by specific user

• Use pinned flags to filter pinned notes

• Sort by add_time, update_time, or content

• Use start/limit for pagination (default limit: 100, max: 500)

Common use cases:

• List all notes for a deal: { "deal_id": 123 }

• List all notes for a person: { "person_id": 456 }

• List pinned notes: { "deal_id": 123, "pinned_to_deal_flag": true }

• List notes by user: { "user_id": 789 }

• Recent notes first: { "sort": "add_time", "sort_by": "desc" }

Get detailed information about a specific note.

Returns note content and metadata including creator, timestamps, and associated entities.

Workflow tips:

• Returns full note content (may include HTML)

• Shows all entities the note is attached to

• Includes creator and last editor information

• Shows pinned status for each entity type

• Useful for retrieving note before updating

Common use cases:

• Get note details: { "id": 123 }

• Verify note content before editing

• Check which entities note is attached to

• View note creator and timestamps

Update an existing note.

Updates note content, entity associations, or pinned status.

Workflow tips:

• All fields except id are optional

• Can update content (supports HTML)

• Can change entity associations

• Can pin/unpin to specific entities

• Content supports rich text formatting

• At least one field should be updated

Common use cases:

• Update content: { "id": 123, "content": "Updated information" }

• Pin to deal: { "id": 123, "pinned_to_deal_flag": true }

• Change association: { "id": 123, "person_id": 456 }

• Update and pin: { "id": 123, "content": "New content", "pinned_to_person_flag": true }

Delete a note from Pipedrive.

Permanently removes a note from all associated entities.

Workflow tips:

• This action cannot be undone

• Note is removed from all associated entities

• Consider using notes_get first to verify the note

• Deleted notes cannot be recovered

Common use cases:

• Remove note: { "id": 123 }

• Clean up old notes

• Remove duplicate or incorrect notes

List all comments for a note with pagination options.

Returns a paginated list of comments associated with a specific note.

Workflow tips:

• Use start/limit for pagination (default limit: 100, max: 500)

• Comments are returned in chronological order

• Each comment includes author information and timestamps

Common use cases:

• Get all comments for a note: { "id": 123 }

• Paginated retrieval: { "id": 123, "start": 0, "limit": 50 }

• Review conversation history on a note

Add a new comment to a note.

Creates a comment on an existing note, allowing for threaded discussions.

Workflow tips:

• content is required

• Comments are added by the authenticated user

• Use this to create conversations around notes

• Comments help track discussions and decisions

Common use cases:

• Add feedback: { "id": 123, "content": "Agreed, let's proceed with this approach" }

• Ask questions: { "id": 456, "content": "Can we clarify the timeline?" }

• Provide updates: { "id": 789, "content": "Completed this action item" }

Update an existing comment on a note.

Modifies the content of a specific comment on a note.

Workflow tips:

• Both note id and comment_id are required

• comment_id is a UUID, not a number

• Only the content can be updated

• Use notes_list_comments to find the comment_id

Common use cases:

• Fix typos: { "id": 123, "comment_id": "uuid-here", "content": "Corrected text" }

• Add details: { "id": 456, "comment_id": "uuid-here", "content": "Updated with more info" }

• Clarify response: { "id": 789, "comment_id": "uuid-here", "content": "Revised answer" }

Delete a comment from a note.

Permanently removes a comment from a note.

Workflow tips:

• This action cannot be undone

• Both note id and comment_id are required

• comment_id is a UUID, not a number

• Use notes_list_comments to find the comment_id

• Deleted comments cannot be recovered

Common use cases:

• Remove comment: { "id": 123, "comment_id": "uuid-here" }

• Clean up inappropriate comments

• Remove duplicate or incorrect comments

Get all field definitions for deals, including custom fields.

Use this to discover what fields are available before creating or updating deals. Returns field keys, types, validation rules, and whether fields are required.

Response includes:

• Field ID and key (use key in API requests)

• Field name and type (varchar, text, enum, date, monetary, etc.)

• Validation info (mandatory, editable, searchable)

• Options for enum/dropdown fields

• Filtering and sorting capabilities

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Discover custom fields before creating deals

• Check field types and validation rules

• Find field keys for API requests

• Understand available enum options

Get all field definitions for persons (contacts), including custom fields.

Use this to discover what fields are available before creating or updating persons. Returns field keys, types, validation rules, and whether fields are required.

Response includes:

• Field ID and key (use key in API requests)

• Field name and type (varchar, text, enum, phone, email, etc.)

• Validation info (mandatory, editable, searchable)

• Options for enum/dropdown fields

• Filtering and sorting capabilities

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Discover custom fields before creating persons

• Check field types and validation rules

• Find field keys for API requests

• Understand available enum options for person fields

Get all field definitions for organizations, including custom fields.

Use this to discover what fields are available before creating or updating organizations. Returns field keys, types, validation rules, and whether fields are required.

Response includes:

• Field ID and key (use key in API requests)

• Field name and type (varchar, text, enum, address, etc.)

• Validation info (mandatory, editable, searchable)

• Options for enum/dropdown fields

• Filtering and sorting capabilities

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Discover custom fields before creating organizations

• Check field types and validation rules

• Find field keys for API requests

• Understand available enum options for organization fields

Get all field definitions for activities, including custom fields.

Use this to discover what fields are available before creating or updating activities. Returns field keys, types, validation rules, and whether fields are required.

Response includes:

• Field ID and key (use key in API requests)

• Field name and type (varchar, text, enum, date, time, etc.)

• Validation info (mandatory, editable, searchable)

• Options for enum/dropdown fields

• Filtering and sorting capabilities

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Discover custom fields before creating activities

• Check field types and validation rules

• Find field keys for API requests

• Understand available enum options for activity fields

Get all field definitions for products, including custom fields.

Use this to discover what fields are available before creating or updating products. Returns field keys, types, validation rules, and whether fields are required.

Response includes:

• Field ID and key (use key in API requests)

• Field name and type (varchar, text, enum, monetary, double, etc.)

• Validation info (mandatory, editable, searchable)

• Options for enum/dropdown fields

• Filtering and sorting capabilities

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Discover custom fields before creating products

• Check field types and validation rules

• Find field keys for API requests

• Understand available enum options for product fields

Get all field definitions available for leads, including custom fields.

Leads share their custom field structure with deals, but this endpoint returns the canonical list as it applies to leads. Read-only — to create/update/delete the underlying custom fields, use the deal field tools (fields_create_deal_field, etc.).

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Discover field keys before creating/updating leads

• Check field types and validation rules

Get all field definitions available for notes.

Read-only — note fields are predefined by Pipedrive and cannot be created, updated, or deleted via the API.

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Discover the structure of note objects

• Find field keys for note payloads

Get details of a specific field by ID and entity type.

Retrieves complete information about a single field definition, including all validation rules, options, and metadata.

Response includes:

• Field ID, key, and name

• Field type and validation rules

• Options for enum fields

• Flags: mandatory, editable, searchable, filterable, sortable, bulk_edit_allowed

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Get specific field details: { "entity_type": "deal", "field_id": 12345 }

• Check field validation rules before updating

• Retrieve enum options for a dropdown field

Get ALL field definitions across all entity types in a single call.

This is a convenient aggregator that fetches field definitions for deals, persons, organizations, activities, and products in one request. Useful for getting a complete overview of all custom fields in your Pipedrive account.

Returns an object with fields grouped by entity type:

• deal_fields: All deal field definitions

• person_fields: All person field definitions

• organization_fields: All organization field definitions

• activity_fields: All activity field definitions

• product_fields: All product field definitions

Each field includes:

• Field ID, key, and name

• Field type and validation rules

• Options for enum fields

• Flags: mandatory, editable, searchable, filterable, sortable

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Get complete field overview across all entities

• Build field mapping documentation

• Audit custom fields setup

• Prepare for data migration or integration

Search for fields by name or key across entity types.

Searches field definitions by matching against field names (case-insensitive) or field keys. Useful for finding specific custom fields when you don't know the exact field ID.

Search is performed across:

• Field names (e.g., "Customer Type", "Lead Source")

• Field keys (e.g., "9dc80c50d78a...")

Results include:

• Entity type the field belongs to

• Field ID, key, and name

• Field type and validation info

• All other field metadata

Cached for 15 minutes as field definitions rarely change.

Common use cases:

• Find field by name: { "query": "customer" }

• Find field by partial key: { "query": "9dc80c" }

• Search in specific entity: { "query": "status", "entity_type": "deal" }

• Find all custom fields containing "date"

Create a new custom field for organizations.

For enum and set field types, you must provide options (a non-empty array of { label } objects).

Common use cases:

• Add a "Customer Type" dropdown to organizations

• Add a custom monetary value (e.g., "Annual Revenue")

• Add a date field (e.g., "Customer Since")

After creation, the field's key is the hash you must use in Organization create/update payloads. Field definitions are cached for 15 minutes — call fields_list_organization_fields after a brief delay to see it reflected.

Update an existing custom organization field.

Note: field_type cannot be changed. For enum/set fields, options is the full set of options after update — include each existing option's id to preserve it, or omit id to add a new option.

Common use cases:

• Rename a field

• Add/remove options on an enum dropdown

• Toggle the field's visibility in the add form

Delete a custom organization field by ID.

This soft-deletes the field on Pipedrive. Existing values are preserved on records but the field stops appearing in the UI and new payloads.

Use fields_bulk_delete_organization_fields to delete several fields in one call.

Delete multiple custom organization fields in a single request.

Accepts either:

• a comma-separated string of field IDs (e.g. "123,456,789")

• an array of numeric IDs (e.g. [123, 456, 789])

Both shapes are normalized to Pipedrive's expected ?ids= query parameter.

Create a new custom field for deals.

For enum and set field types, you must provide options (a non-empty array of { label } objects).

Common use cases:

• Add a "Deal Source" dropdown to deals

• Add a custom monetary value (e.g., "Expected Upsell")

• Add a date field (e.g., "Contract Start Date")

After creation, the field's key is the hash you must use in Deal create/update payloads. Field definitions are cached for 15 minutes — call fields_list_deal_fields after a brief delay to see it reflected.

Update an existing custom deal field.

Note: field_type cannot be changed. For enum/set fields, options is the full set of options after update — include each existing option's id to preserve it, or omit id to add a new option.

Common use cases:

• Rename a field

• Add/remove options on an enum dropdown

• Toggle the field's visibility in the add form

Delete a custom deal field by ID.

This soft-deletes the field on Pipedrive. Existing values are preserved on records but the field stops appearing in the UI and new payloads.

Use fields_bulk_delete_deal_fields to delete several fields in one call.

Delete multiple custom deal fields in a single request.

Accepts either:

• a comma-separated string of field IDs (e.g. "123,456,789")

• an array of numeric IDs (e.g. [123, 456, 789])

Both shapes are normalized to Pipedrive's expected ?ids= query parameter.

Create a new custom field for persons.

For enum and set field types, you must provide options (a non-empty array of { label } objects).

Common use cases:

• Add a "Lead Source" dropdown to persons

• Add a custom text field (e.g., "LinkedIn URL")

• Add a date field (e.g., "Birthday")

After creation, the field's key is the hash you must use in Person create/update payloads. Field definitions are cached for 15 minutes — call fields_list_person_fields after a brief delay to see it reflected.

Update an existing custom person field.

Note: field_type cannot be changed. For enum/set fields, options is the full set of options after update — include each existing option's id to preserve it, or omit id to add a new option.

Common use cases:

• Rename a field

• Add/remove options on an enum dropdown

• Toggle the field's visibility in the add form

Delete a custom person field by ID.

This soft-deletes the field on Pipedrive. Existing values are preserved on records but the field stops appearing in the UI and new payloads.

Use fields_bulk_delete_person_fields to delete several fields in one call.

Delete multiple custom person fields in a single request.

Accepts either:

• a comma-separated string of field IDs (e.g. "123,456,789")

• an array of numeric IDs (e.g. [123, 456, 789])

Both shapes are normalized to Pipedrive's expected ?ids= query parameter.

Create a new custom field for products.

For enum and set field types, you must provide options (a non-empty array of { label } objects).

Common use cases:

• Add a "Product Category" dropdown to products

• Add a custom text field (e.g., "SKU Code")

• Add a numeric field (e.g., "Weight (kg)")

After creation, the field's key is the hash you must use in Product create/update payloads. Field definitions are cached for 15 minutes — call fields_list_product_fields after a brief delay to see it reflected.

Update an existing custom product field.

Note: field_type cannot be changed. For enum/set fields, options is the full set of options after update — include each existing option's id to preserve it, or omit id to add a new option.

Common use cases:

• Rename a field

• Add/remove options on an enum dropdown

• Toggle the field's visibility in the add form

Delete a custom product field by ID.

This soft-deletes the field on Pipedrive. Existing values are preserved on records but the field stops appearing in the UI and new payloads.

Use fields_bulk_delete_product_fields to delete several fields in one call.

Delete multiple custom product fields in a single request.

Accepts either:

• a comma-separated string of field IDs (e.g. "123,456,789")

• an array of numeric IDs (e.g. [123, 456, 789])

Both shapes are normalized to Pipedrive's expected ?ids= query parameter.

Get all field definitions for projects, including custom fields (API v2).

Returns field codes, types and options. Cached for 15 minutes.

Common use cases:

• Discover project custom fields and their field codes

• Check field types before creating/updating projects

Create a new custom field for projects (API v2).

For enum and set field types you must provide options (a non-empty array of { label } objects). The created field's field_code is what you use to update or delete it later.

Update an existing project field (API v2).

Provide the field_code and any of name / options. Field type cannot be changed.

Delete a project field by its field code (API v2).

Get performance metrics for the MCP server.

Returns comprehensive statistics about the server's performance including:

• Request counts and error rates

• Average response times

• Requests and errors by endpoint

• Cache statistics (size, hit rate)

• Rate limiter statistics

Useful for monitoring server health, debugging performance issues, and understanding usage patterns.

Metrics are always fresh (not cached) to provide real-time data.

Response includes:

• requestCount: Total number of API requests made

• errorCount: Total number of failed requests

• totalDuration: Cumulative request duration in milliseconds

• averageDuration: Average request duration in milliseconds

• errorRate: Percentage of requests that failed (0.0 to 1.0)

• requestsByEndpoint: Request count breakdown by endpoint

• errorsByEndpoint: Error count breakdown by endpoint

• cacheStats: Current cache size and statistics

• rateLimiterStats: Rate limiter queue and token information

• timestamp: Current server time

Common use cases:

• Monitor server performance

• Debug slow responses or errors

• Analyze usage patterns

• Check cache effectiveness

Check API connectivity and authentication status.

Verifies that the Pipedrive API is accessible and the authentication token is valid by making a test request to GET /users/me.

Returns:

• healthy: Boolean indicating if the API is accessible

• user: Current authenticated user information (if healthy)

• timestamp: Time of the health check

• error: Error details if unhealthy

Cached for 60 seconds to avoid excessive health checks.

Common use cases:

• Verify API token is valid

• Check if Pipedrive API is accessible

• Get basic connection status before performing operations

• Troubleshoot authentication issues

Get information about the currently authenticated user.

Returns complete details about the user associated with the API token, including:

• User ID, name, and email

• Account permissions and role

• Default currency and language

• Timezone and locale settings

• Company information

• Account limits and features

This is useful for understanding the context and permissions of the current API session.

Cached for 60 seconds as user information rarely changes during a session.

Response includes:

• id: User ID

• name: Full name

• email: Email address

• role_id: User's role ID

• timezone: User's timezone (e.g., "America/New_York")

• locale: User's locale (e.g., "en_US")

• default_currency: Default currency code

• is_admin: Whether user is an admin

• activated: Whether account is activated

• company_id: Company ID

• company_name: Company name

Common use cases:

• Get user context for operations

• Check user permissions

• Retrieve timezone for date/time operations

• Get default currency for monetary fields

Get list of supported currencies and exchange rates.

Returns all currencies configured in your Pipedrive account, including:

• Currency codes (USD, EUR, GBP, etc.)

• Currency symbols and names

• Exchange rates relative to account's default currency

• Whether currency is active

• Decimal precision

This is essential for working with monetary fields and understanding currency conversions in deals and products.

Cached for 24 hours as currency rates don't change frequently in Pipedrive configuration.

Response includes array of currencies with:

• id: Currency ID

• code: ISO 4217 currency code (e.g., "USD", "EUR")

• name: Full currency name (e.g., "US Dollar")

• symbol: Currency symbol (e.g., "$", "€")

• decimal_points: Number of decimal places

• is_custom_flag: Whether it's a custom currency

• active_flag: Whether currency is active

Common use cases:

• Get supported currencies before creating deals

• Validate currency codes for monetary fields

• Understand exchange rates for reporting

• Check which currencies are active in the account

Clear all cached data from the MCP server.

Removes all entries from the cache, forcing fresh API requests for subsequent operations. This is useful for:

• Debugging cache-related issues

• Forcing refresh of stale data

• Testing without cached responses

• Resetting after bulk data changes

Returns the number of cache entries that were cleared.

CAUTION: This will impact performance temporarily as all subsequent requests will need to fetch fresh data from the Pipedrive API. The cache will repopulate naturally as requests are made.

Response includes:

• message: Confirmation message

• previousSize: Number of cache entries that were cleared

• timestamp: Time when cache was cleared

Common use cases:

• Debug stale or incorrect cached data

• Force refresh after bulk imports or updates

• Test API behavior without cache

• Clear cache after configuration changes

Get all add-ons for a single company.

Returns the add-ons (billing subscriptions) configured for your Pipedrive company account.

Add-ons include features like:

• LeadBooster (lead generation tools)

• Prospector (contact database access)

• Smart Docs (document management)

• And other premium features

This is useful for:

• Checking which premium features are enabled

• Understanding account capabilities

• Determining available integrations

• Auditing subscription status

Cached for 24 hours as add-on configuration doesn't change frequently.

Response includes array of add-on codes:

• code: Add-on identifier (e.g., "leadbooster_v2", "prospector", "smart_docs_v2")

Common use cases:

• Check if LeadBooster is available before using lead features

• Verify Smart Docs access for document operations

• List all active premium features

• Audit company subscriptions

Get recently viewed or modified items.

Returns data about all recent changes that occurred after the given timestamp. This is useful for tracking activity, syncing data, or showing users what they've recently worked on.

Required fields:

• since_timestamp: Timestamp in UTC (YYYY-MM-DD HH:MM:SS format)

Optional fields:

• items: Filter by specific item types (comma-separated)

• start: Pagination start (default: 0)

• limit: Items shown per page

Supported item types:

• activity

• deal

• person

• organization

• product

• note

• file

• mail

• etc.

Workflow tips:

• Use ISO 8601 or YYYY-MM-DD HH:MM:SS format for timestamps

• Filter by item type to reduce response size

• Use pagination for large result sets

• Track changes since last sync

Common use cases:

• Recent activity: { "since_timestamp": "2024-12-10 10:00:00" }

• Recent deals only: { "since_timestamp": "2024-12-10 10:00:00", "items": "deal" }

• Multiple types: { "since_timestamp": "2024-12-10 10:00:00", "items": "deal,person,organization" }

• Paginated results: { "since_timestamp": "2024-12-10 10:00:00", "start": 0, "limit": 50 }

Get all user connections for the authorized user.

Returns data about all external service connections (integrations) for the currently authorized user. This shows which third-party services the user has connected to their Pipedrive account.

Common connections include:

• Google (Gmail, Calendar, Drive)

• Microsoft (Outlook, Office 365)

• Video calling services

• Email providers

• Calendar services

• And other integrations

This is useful for:

• Checking which services are connected

• Verifying integration status

• Debugging connection issues

• Auditing user integrations

Response includes:

• Service name as key (e.g., "google")

• Connection ID as value (e.g., "awesomeid-123-4567890")

Common use cases:

• Check if Google is connected before using Gmail features

• Verify email integration status

• List all user integrations

• Troubleshoot sync issues

List settings of the authorized user.

Returns all configuration settings for the currently authorized Pipedrive user. This includes personal preferences, feature flags, limits, and account-specific configurations.

Common settings include:

• list_limit: Default pagination size (e.g., 100)

• beta_app: Beta features access

• file_upload_destination: Storage location (e.g., "s3")

• callto_link_syntax: Phone call link format

• autofill_deal_expected_close_date: Auto-fill deal dates

• person_duplicate_condition: Duplicate detection rules

• marketplace_team: Marketplace team access

• And many other preferences

This is useful for:

• Understanding user preferences

• Checking feature access

• Debugging user-specific issues

• Auditing account configuration

• Determining default behaviors

Cached for 1 hour as settings don't change frequently.

Response includes key-value pairs of settings:

• Setting name as key

• Setting value as value (boolean, number, or string)

Common use cases:

• Check list_limit before pagination

• Verify beta feature access

• Understand duplicate detection rules

• Get default behaviors for operations

List all products with optional filtering and pagination.

Supports filtering by:

• user_id: Filter by owner

• filter_id: Apply a saved filter

• ids: Array of specific product IDs to return

• first_char: Filter by first character of name (single letter)

• get_summary: Include total count in response

Returns paginated results. Use start/limit for manual pagination.

Automatically fetch ALL products using pagination.

This tool handles pagination automatically and returns all products matching the filters. Use this when you need the complete list without managing pagination manually.

Warning: This can return a large dataset if you have many products.

Supports the same filters as products/list:

• user_id: Filter by owner

• filter_id: Apply a saved filter

• first_char: Filter by first character of name

Create a new product in Pipedrive.

Required fields:

• name: Product name

Optional fields:

• code: Product code (SKU)

• description: Product description

• unit: Unit type (e.g., "pcs", "kg", "hours")

• tax: Tax percentage (0-100)

• active_flag: Whether product is active (default: true)

• selectable: Whether product can be selected in deals (default: true)

• visible_to: Visibility level (1=owner only, 3=entire company)

• owner_id: User who will own this product

• prices: Array of price objects with format: [{"price": 100, "currency": "USD", "cost": 50}]

• billing_frequency: One of: one-time, weekly, monthly, quarterly, semi-annually, annually

• billing_frequency_cycles: Number of billing cycles

Custom fields:

• Pass display names: { "custom_fields": { "SKU Class": "A", "Category": "Electronics" } }

• Or hash keys directly: { "custom_fields": { "abc123...": "raw value" } }

• For enum/set fields, pass option labels (not ids).

Example prices array: { "prices": [ {"price": 100, "currency": "USD", "cost": 50, "overhead_cost": 10, "notes": "Standard price"}, {"price": 85, "currency": "EUR", "cost": 45} ] }

Get detailed information about a specific product.

Returns complete product data including:

• Basic information (name, code, description, unit)

• Pricing information (prices array with different currencies)

• Billing information (frequency, cycles)

• Metadata (owner, visibility, timestamps)

• Tax and category information

Use this when you need full details about a product, such as:

• Viewing complete product specifications

• Getting pricing information

• Checking product availability and status

Update an existing product in Pipedrive.

All fields are optional except id. Only provide the fields you want to update.

Updatable fields:

• name: Product name

• code: Product code (SKU)

• description: Product description

• unit: Unit type

• tax: Tax percentage

• active_flag: Whether product is active

• selectable: Whether product can be selected in deals

• visible_to: Visibility level

• owner_id: Product owner

• prices: Array of price objects

• billing_frequency: Billing frequency

• billing_frequency_cycles: Number of billing cycles

Note: When updating prices, the entire prices array is replaced.

Custom fields:

• Pass display names: { "custom_fields": { "SKU Class": "A", "Category": "Electronics" } }

• Or hash keys directly: { "custom_fields": { "abc123...": "raw value" } }

• For enum/set fields, pass option labels (not ids).

Delete a product from Pipedrive.

The product will be marked as deleted and after 30 days will be permanently deleted.

Note: Deleting a product does not automatically remove it from existing deals. Deals that already have this product attached will keep the product information.

This is useful for:

• Discontinuing products

• Cleaning up old inventory

• Removing test products

Search for products by name, code, or custom fields.

This is a powerful search tool that finds products matching your query across multiple fields.

Search features:

• Searches product name, code, and custom fields by default

• Minimum 1 character required (or use exact_match for single chars)

• Returns relevance-scored results

• Supports pagination

Use cases:

• Finding products by partial name

• Looking up products by code/SKU

• Searching custom product attributes

• Quick product lookup during deal creation

Get all deals where a specific product is attached.

Returns a list of deals that have this product in their products list. This is useful for:

• Tracking product usage across deals

• Analyzing product performance

• Finding deals with specific products

• Revenue forecasting by product

Filter options:

• status: Filter by deal status (open, won, lost, deleted, all_not_deleted)

Each deal includes full deal information plus product attachment details.

List all files attached to a specific product.

Returns files associated with the product such as:

• Product images

• Documentation

• Specifications

• Contracts

• Other attachments

Supports sorting by:

• id: File ID

• update_time: Last update time

Use this for:

• Viewing product documentation

• Accessing product images

• Managing product attachments

Add a follower to a product.

Followers are users who will receive notifications about updates to this product. This is useful for team collaboration and keeping stakeholders informed.

When a user follows a product, they will be notified about:

• Changes to product details

• Product being added to deals

• Price changes

• Other updates

Note: Users can only be added as followers if they have access to the product.

List all followers of a specific product.

Returns a list of users who are following this product and will receive notifications about updates.

Each follower entry includes:

• User ID

• Follower ID (relationship ID)

• Product ID

• When they started following

This is useful for:

• Checking who is tracking a product

• Auditing team access

• Managing notifications

Remove a follower from a product.

Stops a user from receiving notifications about this product.

Note: You need the follower_id (the relationship ID), not the user_id. Get this from the products/list_followers endpoint.

List all users who have access to view and edit a specific product.

Returns a list of users who have permission to access this product based on visibility settings and team structure.

Workflow tips:

• Product visibility determines which users can access it

• Visibility can be: owner only, owner's team, entire company, or custom

• This is useful for understanding who can see and modify the product

• Access permissions affect whether users can add the product to deals

Common use cases:

• Audit product access permissions

• Verify team members can see a product

• Check visibility before sharing product with team

• Troubleshoot why a user cannot see a product

Example: { "id": 123 }

List leads with pagination and filtering options.

Returns a paginated list of non-archived leads. Use filters to narrow results by owner, person, or organization.

Workflow tips:

• Leads are sorted by creation time (oldest to newest)

• Use owner_id to filter by lead owner

• Use person_id or organization_id to filter by associated entities

• filter_id takes precedence over other filters

• Use start/limit for pagination (default limit: 100, max: 500)

• For all leads without pagination, use leads/list_all_auto instead

• Use add_time_from / add_time_until to filter by creation date (client-side). NOTE: this only filters the current page; for complete date-range results use leads/list_all_auto

• Leads inherit custom fields structure from deals

Common use cases:

• List all leads: {}

• List leads for a specific owner: { "owner_id": 123 }

• List leads for a person: { "person_id": 456 }

• List leads for an organization: { "organization_id": 789 }

Automatically fetch ALL leads with pagination handling.

This tool automatically handles pagination and fetches all non-archived leads matching the filters. Unlike leads/list, this returns ALL results in a single response.

WARNING: This can return large datasets. Use filters to limit results.

Workflow tips:

• Same filters as leads/list (owner_id, person_id, organization_id, filter_id)

• Specify max_items to limit total results if needed

• No need to manage start/limit - pagination is automatic

• Best for exports, reports, or comprehensive analysis

• Leads are sorted by creation time (oldest to newest)

Common use cases:

• Get all leads: {}

• Export all leads for a user: { "owner_id": 123 }

• Get all leads for analysis: { "max_items": 1000 }

List archived leads with pagination and filtering options.

Returns a paginated list of archived leads. Archived leads are leads that have been moved out of the active Leads Inbox but not deleted or converted to deals.

Workflow tips:

• Archived leads are sorted by creation time (oldest to newest)

• Use owner_id to filter by lead owner

• Use person_id or organization_id to filter by associated entities

• filter_id takes precedence over other filters

• Use start/limit for pagination (default limit: 100, max: 500)

• Archived leads can be restored to active status using leads/update

Common use cases:

• List all archived leads: {}

• List archived leads for a specific owner: { "owner_id": 123 }

• List archived leads for a person: { "person_id": 456 }

• Review archived leads before deletion: { "limit": 50 }

Create a new lead in Pipedrive.

Creates a new lead with the specified information. A lead must be linked to a person or an organization (or both). All leads created through the API will have source_name "API" and origin "API".

Custom fields:

• Pass display names: { "custom_fields": { "Source": "Web", "Budget": 5000 } }

• Or hash keys directly: { "custom_fields": { "abc123...": "raw value" } }

• Uses deal field definitions (leads share the deal custom fields).

Workflow tips:

• Title is required

• Must have person_id, organization_id, or both

• Use persons/search or organizations/search to get IDs

• Value is optional but recommended (object with amount and currency)

• Leads inherit custom fields structure from deals

• Set expected_close_date in YYYY-MM-DD format

• label_ids is an array of UUID strings

Common use cases:

• Simple lead: { "title": "New Lead", "person_id": 123 }

• Lead with value: { "title": "Lead", "person_id": 123, "value": { "amount": 5000, "currency": "USD" } }

• Lead with org: { "title": "Company Lead", "organization_id": 456 }

• Full lead: { "title": "Big Lead", "person_id": 123, "organization_id": 456, "value": { "amount": 50000, "currency": "USD" }, "expected_close_date": "2024-12-31", "owner_id": 1 }

Get details of a specific lead by UUID.

Returns detailed information about a single lead including all fields and custom field values.

Workflow tips:

• Lead IDs are UUIDs (not integers like other entities)

• Use leads/search to find leads by title or other fields

• Custom fields from deals are inherited by leads

• Only set custom field values will appear in response

Common use cases:

• Get lead details: { "id": "adf21080-0e10-11eb-879b-05d71fb426ec" }

• Retrieve lead for update: { "id": "" }

Update an existing lead in Pipedrive.

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 value, person_id, or organization_id).

Custom fields:

• Pass display names: { "custom_fields": { "Source": "Web", "Budget": 5000 } }

• Or hash keys directly: { "custom_fields": { "abc123...": "raw value" } }

• Uses deal field definitions (leads share the deal custom fields).

Workflow tips:

• Only include fields you want to update

• Lead ID must be a UUID

• Use null to clear optional fields

• value must be an object with amount and currency

• Leads inherit custom fields structure from deals

• Set is_archived to true to archive a lead

Common use cases:

• Update title: { "id": "", "title": "Updated Title" }

• Update value: { "id": "", "value": { "amount": 10000, "currency": "USD" } }

• Archive lead: { "id": "", "is_archived": true }

• Clear person: { "id": "", "person_id": null }

Delete a specific lead from Pipedrive.

Permanently deletes a lead by its UUID. This action cannot be undone.

Workflow tips:

• Lead ID must be a UUID

• This permanently deletes the lead

• Consider archiving instead (use leads/update with is_archived: true)

• Returns the deleted lead's ID on success

Common use cases:

• Delete a lead: { "id": "adf21080-0e10-11eb-879b-05d71fb426ec" }

Alternative:

• Archive instead of delete: Use leads/update with { "id": "", "is_archived": true }

Search leads by title, notes, and custom fields.

Searches all leads by title, notes, and/or custom fields using a search term. This is a wrapper of /v1/itemSearch with a narrower OAuth scope.

Workflow tips:

• Minimum 2 characters for search term (or 1 with exact_match)

• Use exact_match for case-insensitive exact matching

• Filter results by person_id or organization_id (max 2000 leads each)

• fields parameter specifies which fields to search (comma-separated)

• Results include result_score for relevance ranking

• Use start/limit for pagination

Common use cases:

• Search by title: { "term": "acme" }

• Exact match: { "term": "Acme Corp", "exact_match": true }

• Search for person's leads: { "term": "deal", "person_id": 123 }

• Search org's leads: { "term": "proposal", "organization_id": 456 }

Get all lead labels (tags/categories).

Returns details of all lead labels available in your Pipedrive account. Lead labels are used to categorize and organize leads.

Workflow tips:

• This endpoint does not support pagination (all labels returned)

• Labels have UUIDs as identifiers

• Use label UUIDs when creating/updating leads

• Labels have name and color properties

• Results are heavily cached (24 hours) as labels change infrequently

Common use cases:

• List all labels: {}

• Get label IDs for lead creation

• Display available labels to users

Response format:

• Returns array of label objects with: id (UUID), name, color, add_time, update_time

Get all lead sources (where leads came from).

Returns all lead sources available in Pipedrive. Lead sources indicate where your leads originated.

Lead sources are pre-defined and cannot be modified. All leads created through the Pipedrive API will automatically have lead source "API" assigned.

Available lead sources:

• Manually created

• Deal

• Web forms

• Prospector

• Leadbooster (includes Chatbot leads)

• Live chat

• Import

• Website visitors

• Workflow automation

• API

Workflow tips:

• Lead sources are fixed and cannot be edited

• This list may expand as new sources are added

• Results are heavily cached (24 hours) as sources rarely change

• Use for reference and reporting purposes

Common use cases:

• List all sources: {}

• Get source information for reports

• Display available sources to users

Create a new lead label.

Required: name + color. Color must be one of: blue, brown, dark-gray, gray, green, orange, pink, purple, red, yellow.

Common use cases:

• Hot lead: { "name": "Hot", "color": "red" }

• Qualified lead: { "name": "Qualified", "color": "green" }

Update an existing lead label.

Provide the label's UUID and any combination of name/color to change.

Delete a lead label by UUID.

Existing leads carrying this label will lose it after deletion.

Convert a lead into a deal (asynchronous, two-step flow).

Step 1 (this tool): POST starts the conversion. Returns { id: conversion_id, status: 'queued' | 'running' }. Step 2 (separate tool): poll leads_convert_status with the lead id AND the conversion_id returned here, every few seconds, until status === 'completed'. The completed response includes the resulting deal_id.

Related entities (notes, files, emails, activities) are transferred to the new deal.

Check the status of a lead-to-deal conversion job.

Use the conversion_id returned by leads_convert_to_deal. Possible statuses: queued, running, completed, failed. When completed, the response includes the resulting deal_id.

List all users within the company.

Returns all users in the Pipedrive company account with their details including roles, permissions, and settings.

Workflow tips:

• Returns all users in a single request (no pagination needed)

• Includes active and inactive users

• Shows user roles, permissions, and access levels

• Cached for 10 minutes for better performance

Common use cases:

• Get all company users: {}

• View user roles and permissions

• Check user active status

Get detailed information about a specific user by ID.

Retrieves complete information about a single user including roles, permissions, timezone, and access settings.

Workflow tips:

• Use users/list to find user IDs first

• Response includes role assignments and permissions

• Cached for 10 minutes for better performance

Common use cases:

• Get user details: { "id": 123 }

• Check user permissions and role

• Verify user active status

Add a new user to the company.

Creates a new user account in the Pipedrive company. Requires admin permissions.

Workflow tips:

• Email is required and must be unique

• User will receive an activation email

• New users are active by default

• Name can be provided or will be derived from email

Common use cases:

• Add new team member: { "name": "John Doe", "email": "john@company.com" }

• Create inactive user: { "name": "Jane Smith", "email": "jane@company.com", "active_flag": false }

Update user details.

Updates information for an existing user. Requires admin permissions.

Workflow tips:

• Only provided fields will be updated

• Use users/get to retrieve current values first

• Email must remain unique if changed

• Cannot update own admin status

Common use cases:

• Update user name: { "id": 123, "name": "John Smith" }

• Change user email: { "id": 123, "email": "newemail@company.com" }

• Deactivate user: { "id": 123, "active_flag": false }

Get information about the current authorized user.

Returns details about the user associated with the API token being used.

Workflow tips:

• No parameters needed

• Useful for checking current user's permissions

• Shows role and access levels

• Cached for 10 minutes

Common use cases:

• Get current user info: {}

• Check own permissions

• Verify API token user

List followers of a user.

Returns all users who are following the specified user.

Workflow tips:

• Shows users tracking this user's activities

• Useful for managing team visibility

• Cached for 10 minutes

Common use cases:

• Get user followers: { "id": 123 }

Add a follower to a user.

Makes one user follow another user's activities.

Workflow tips:

• Follower will see activities of followed user

• Useful for team collaboration and visibility

• Requires appropriate permissions

Common use cases:

• Add follower: { "id": 123, "user_id": 456 }

Remove a follower from a user.

Removes the follower relationship between two users.

Workflow tips:

• Follower will stop seeing followed user's activities

• Use users/list_followers to get follower IDs

Common use cases:

• Remove follower: { "id": 123, "follower_id": 456 }

Get user permissions.

Returns all permissions assigned to the specified user including access levels and restrictions.

Workflow tips:

• Shows detailed permission breakdown

• Includes app-specific permissions

• Useful for auditing user access

• Cached for 10 minutes

Common use cases:

• Get user permissions: { "id": 123 }

• Audit user access levels

• Verify permissions before operations

List user role settings.

Returns all role-based settings for the specified user.

Workflow tips:

• Shows role-specific configurations

• Includes inherited settings from role hierarchy

• Useful for understanding user capabilities

• Cached for 10 minutes

Common use cases:

• Get role settings: { "id": 123 }

• Review user's role configuration

• Check visibility and access settings

Find users by name or email.

Searches for users within the company by name or email address. Returns matching users with their details.

Workflow tips:

• Faster than filtering users/list results

• Can search by name (default) or email

• Partial matches are supported

• Useful for autocomplete and user lookup

• Cached for 5 minutes

Common use cases:

• Find by name: { "term": "John" }

• Find by email: { "term": "john@example.com", "search_by_email": 1 }

• Quick user lookup for assignments

List role assignments for a user.

Returns all role assignments for a specific user with pagination support.

Workflow tips:

• Shows all roles assigned to the user

• Includes role hierarchy information

• Use pagination for users with many role assignments

• Cached for 10 minutes

• Useful for auditing user permissions

Common use cases:

• List all role assignments: { "id": 123 }

• Paginated list: { "id": 123, "start": 0, "limit": 50 }

• Check user's current roles

List all roles within the company.

Returns all roles with pagination support, including role hierarchy and assignment counts.

Workflow tips:

• Shows role hierarchy with parent_role_id

• Includes assignment and sub-role counts

• Use pagination for companies with many roles

• Cached for 15 minutes for better performance

Common use cases:

• List all roles: {}

• Paginated list: { "start": 0, "limit": 50 }

• View role hierarchy and structure

Get detailed information about a specific role by ID.

Retrieves complete information about a single role including hierarchy, assignments, and settings.

Workflow tips:

• Use roles/list to find role IDs first

• Response includes parent role and hierarchy level

• Shows assignment counts

• Cached for 15 minutes for better performance

Common use cases:

• Get role details: { "id": 123 }

• Check role hierarchy

• View role assignment count

Add a new role to the company.

Creates a new role with optional parent role for hierarchy. Requires admin permissions.

Workflow tips:

• Name is required and should be unique

• Parent role creates hierarchy

• New roles start with default permissions

• Use roles/add_role_setting to configure permissions

Common use cases:

• Create top-level role: { "name": "Sales Team" }

• Create sub-role: { "name": "Junior Sales", "parent_role_id": 123 }

Update role details.

Updates information for an existing role. Requires admin permissions.

Workflow tips:

• Only provided fields will be updated

• Use roles/get to retrieve current values first

• Changing parent_role_id affects hierarchy

• Name should remain unique

Common use cases:

• Rename role: { "id": 123, "name": "Senior Sales Team" }

• Change hierarchy: { "id": 123, "parent_role_id": 456 }

Delete a role.

Removes a role from the company. Requires admin permissions.

Workflow tips:

• Cannot delete role with active assignments

• Use roles/get_role_assignments to check assignments first

• Remove all assignments before deletion

• Sub-roles may need to be reassigned

Common use cases:

• Delete unused role: { "id": 123 }

Get role assignments.

Returns all users assigned to a specific role with pagination support.

Workflow tips:

• Shows all users with this role

• Use pagination for roles with many users

• Useful for auditing role membership

• Cached for 15 minutes

Common use cases:

• Get role assignments: { "id": 123 }

• Paginated list: { "id": 123, "start": 0, "limit": 50 }

Add a role assignment.

Assigns a role to a user. Requires admin permissions.

Workflow tips:

• User can have only one role at a time

• Previous role assignment will be replaced

• User inherits all role permissions

• Changes take effect immediately

Common use cases:

• Assign role to user: { "id": 123, "user_id": 456 }

Delete a role assignment.

Removes a role from a user. Requires admin permissions.

Workflow tips:

• User will lose role permissions

• User should be assigned to another role

• Use roles/get_role_assignments to verify removal

Common use cases:

• Remove role from user: { "id": 123, "user_id": 456 }

Get role settings.

Returns all settings configured for a specific role.

Workflow tips:

• Shows all role-specific configurations

• Includes visibility and permission settings

• Useful for understanding role capabilities

• Cached for 15 minutes

Common use cases:

• Get role settings: { "id": 123 }

• Audit role configuration

Add or update a role setting.

Creates or updates a setting for a role. Requires admin permissions.

Workflow tips:

• Setting key should follow Pipedrive conventions

• Value can be string, number, or boolean

• Creates new setting or updates existing one

• Changes affect all users with this role

Common use cases:

• Add setting: { "id": 123, "setting_key": "visibility", "value": "shared" }

• Enable feature: { "id": 123, "setting_key": "can_export_data", "value": true }

Update a role setting.

Updates an existing setting for a role. Requires admin permissions.

Workflow tips:

• Setting must already exist

• Use roles/get_role_settings to see current settings

• Changes affect all users with this role

• Value type should match original setting

Common use cases:

• Update setting: { "id": 123, "setting_key": "visibility", "value": "private" }

Delete a role setting.

Removes a setting from a role. Requires admin permissions.

Workflow tips:

• Reverts to default value if available

• Use roles/get_role_settings to see current settings

• Changes affect all users with this role

Common use cases:

• Remove setting: { "id": 123, "setting_key": "custom_permission" }

List pipeline visibility for a role.

Returns all pipelines and their visibility status for a specific role. For more information on pipeline visibility, please refer to the Visibility groups article.

Workflow tips:

• Shows which pipelines are visible/hidden for the role

• Use visible parameter to filter only visible pipelines

• Useful for managing pipeline access by role

• Cached for 15 minutes

Common use cases:

• List all pipelines for role: { "id": 123 }

• List only visible pipelines: { "id": 123, "visible": true }

• Audit pipeline visibility settings

Update pipeline visibility for a role.

Updates the specified pipelines to be visible and/or hidden for a specific role. For more information on pipeline visibility, please refer to the Visibility groups article.

Workflow tips:

• Use object with pipeline IDs as keys and 1/0 as values

• 1 = visible, 0 = hidden

• Requires admin permissions

• Changes affect all users with this role

• Use roles/list_role_pipelines to see current visibility

Common use cases:

• Make pipelines visible: { "id": 123, "visible_pipeline_ids": { "1": 1, "2": 1 } }

• Hide specific pipelines: { "id": 123, "visible_pipeline_ids": { "3": 0 } }

• Mix visibility: { "id": 123, "visible_pipeline_ids": { "1": 1, "2": 0 } }

Get all webhooks configured for the company.

Returns a list of all webhooks that have been created in Pipedrive, including:

• Active and inactive webhooks

• Event triggers (action + object combinations)

• Subscription URLs

• Authentication settings

• Last delivery information

Note: Webhook data is always fetched fresh (no caching) to ensure you see the current state.

Common use cases:

• List all active webhooks: Review current webhook configurations

• Audit webhook endpoints: Check which URLs are receiving notifications

• Debug webhook issues: View last delivery time and HTTP status

• Manage webhooks: Get webhook IDs before updating or deleting

Event combinations explained:

• event_action: added, updated, deleted, merged, or * (all)

• event_object: activity, deal, person, organization, note, pipeline, product, stage, user, or * (all)

• Examples: "added.deal", "updated.person", "deleted.organization", "." (all events)

Webhook fields returned:

• id: Webhook ID

• subscription_url: The URL that receives webhook notifications

• event_action & event_object: The trigger combination

• is_active: Whether the webhook is currently active

• add_time: When the webhook was created

• last_delivery_time: Last successful delivery timestamp

• last_http_status: HTTP status code from last delivery attempt

• version: Webhook API version (1.0 or 2.0)

• name: Optional webhook name

Create a new webhook to receive real-time notifications from Pipedrive.

Creates a webhook that will send HTTP POST requests to your endpoint when specified events occur.

Required fields:

• subscription_url: The HTTPS endpoint that will receive webhook notifications

• event_action: The action that triggers the webhook

• event_object: The object type that triggers the webhook

Webhook triggers (event_action + event_object):

• Event Actions: added, updated, deleted, merged, * (all)

• Event Objects: activity, activityType, deal, note, organization, person, pipeline, product, stage, user, * (all)

Common webhook combinations:

• New deals: { "event_action": "added", "event_object": "deal" }

• Updated persons: { "event_action": "updated", "event_object": "person" }

• Deleted organizations: { "event_action": "deleted", "event_object": "organization" }

• All events: { "event_action": "", "event_object": "" }

• All deal events: { "event_action": "*", "event_object": "deal" }

Security:

• Use HTTPS URLs for security

• Optionally add HTTP Basic Auth with http_auth_user and http_auth_password

• Both auth fields must be provided together

Version:

• version: "2.0" (recommended, default) or "1.0" (legacy)

• v2.0 includes more data and better structure

Workflow tips:

1. Set up your endpoint first to handle POST requests

2. Create the webhook with appropriate event filters

3. Test with webhooks/list to verify creation

4. Monitor last_delivery_time and last_http_status for debugging

5. Your endpoint should return 200-299 status code to acknowledge receipt

Example payloads:

• Simple webhook: { "subscription_url": "https://example.com/webhook", "event_action": "added", "event_object": "deal" }

• With auth: { "subscription_url": "https://example.com/webhook", "event_action": "updated", "event_object": "person", "http_auth_user": "user", "http_auth_password": "pass" }

• All events: { "subscription_url": "https://example.com/webhook", "event_action": "", "event_object": "", "name": "All Events Webhook" }

Important notes:

• Pipedrive will send a test request immediately after creation

• Your endpoint must be accessible from Pipedrive servers

• Webhooks that repeatedly fail may be automatically disabled

• See Pipedrive documentation for webhook payload structure

Delete a webhook by its ID.

Permanently removes a webhook from Pipedrive. Once deleted, the webhook will no longer send notifications to the subscription URL.

When to delete webhooks:

• The endpoint URL is no longer valid or in use

• You want to stop receiving notifications for specific events

• You're cleaning up test/development webhooks

• The integration using the webhook has been decommissioned

• The webhook is failing consistently and needs to be recreated

Workflow:

1. Use webhooks/list to get the ID of the webhook you want to delete

2. Call webhooks/delete with the webhook ID

3. Confirm deletion was successful

Important notes:

• This action is permanent and cannot be undone

• Deleting a webhook will immediately stop all notifications

• You can recreate a webhook with the same settings later if needed

• Use webhooks/list after deletion to verify it was removed

Example:

• Delete webhook: { "id": 123 }

Best practices:

• Always verify the webhook ID before deletion

• Document which webhooks are deleted and why

• Consider disabling temporarily instead if you might need it again

• Keep track of webhook configurations for recreating if needed

List all filters in Pipedrive.

Returns data about all filters. Each filter is a set of conditions used to filter items.

Workflow tips:

• Use type parameter to filter by entity type (deals, org, people, products, activities)

• Without type parameter, returns all filters across all types

• Filters can be applied when fetching lists of deals, leads, persons, organizations, or products

• Results are heavily cached for 15 minutes for optimal performance

Common use cases:

• List all filters: {}

• List deal filters only: { "type": "deals" }

• List organization filters: { "type": "org" }

• List people filters: { "type": "people" }

Get a specific filter by ID.

Returns detailed data about a specific filter, including its condition lines.

Workflow tips:

• Returns complete filter configuration including conditions structure

• Use filters/list to discover available filter IDs

• The conditions field contains the filter's logic (glue, conditions array)

• Results are heavily cached for 15 minutes

Common use cases:

• Get filter details: { "id": 123 }

• Inspect filter conditions: { "id": 456 }

Create a new filter in Pipedrive.

Adds a new filter with conditions. Returns the filter ID upon success.

IMPORTANT LIMITATIONS:

• Only ONE first-level condition group is supported (must be glued with 'AND')

• Only TWO second-level condition groups are supported

• First second-level group must be glued with 'AND'

• Second second-level group must be glued with 'OR'

• Maximum of 16 conditions per filter

Workflow tips:

• Use filters/helpers to discover available field IDs and operators

• Structure: { glue: "and", conditions: [{ glue: "and", conditions: [...] }, { glue: "or", conditions: [...] }] }

• Common operators: =, !=, <, >, <=, >=, LIKE, IN, IS NULL, IS NOT NULL

• Filter types: deals, org, people, products, activities

Example simple filter: { "name": "High value deals", "type": "deals", "conditions": { "glue": "and", "conditions": [ { "glue": "and", "conditions": [ { "object": "deal", "field_id": "value", "operator": ">", "value": 10000 } ] }, { "glue": "or", "conditions": [null] } ] } }

Update an existing filter in Pipedrive.

Updates a filter's name and/or conditions. Only provide fields you want to change.

IMPORTANT LIMITATIONS:

• Only ONE first-level condition group is supported (must be glued with 'AND')

• Only TWO second-level condition groups are supported

• First second-level group must be glued with 'AND'

• Second second-level group must be glued with 'OR'

• Maximum of 16 conditions per filter

Workflow tips:

• Use filters/get to see current filter configuration before updating

• Use filters/helpers to discover available field IDs and operators

• Can update name only, conditions only, or both

• Common operators: =, !=, <, >, <=, >=, LIKE, IN, IS NULL, IS NOT NULL

Common use cases:

• Rename filter: { "id": 123, "name": "New Name" }

• Update conditions: { "id": 123, "conditions": {...} }

• Update both: { "id": 123, "name": "Updated", "conditions": {...} }

Delete a filter in Pipedrive.

Marks a filter as deleted. The filter will no longer be available for use.

Workflow tips:

• Use filters/list to find filter IDs to delete

• Use filters/get to verify filter details before deletion

• For deleting multiple filters at once, use filters/bulk_delete instead

• Deletion is permanent and cannot be undone

Common use cases:

• Delete a specific filter: { "id": 123 }

• Remove unused filter: { "id": 456 }

Delete multiple filters at once in Pipedrive.

Marks multiple filters as deleted in a single operation. More efficient than deleting one at a time.

Workflow tips:

• Provide comma-separated filter IDs as a string (e.g., "1,2,3,4")

• Use filters/list to find filter IDs to delete

• All specified filters will be deleted in one API call

• Deletion is permanent and cannot be undone

Common use cases:

• Delete multiple filters: { "ids": "123,456,789" }

• Clean up old filters: { "ids": "1,2,3,4,5" }

Get all available filter helpers and field types.

Returns comprehensive information about what conditions and helpers are available for creating/updating filters.

This tool helps you understand:

• What field IDs are available for each object type

• What operators can be used with each field

• Field data types (text, number, date, etc.)

• Available options for enum/select fields

• Helper types for building filter UIs

Workflow tips:

• Use this BEFORE creating or updating filters to know available fields

• Essential for understanding what field_id values to use in conditions

• Shows which operators are valid for each field type

• Results are heavily cached for 15 minutes

• No parameters needed - returns all available helpers

Common use cases:

• Discover available deal fields: {}

• Find person field IDs: {}

• Check valid operators for a field: {}

• Get dropdown options for enum fields: {}

List projects with cursor-based pagination. Returns projects with filtering options by status, phase, and archive state.

Get details of a specific project by ID. Returns complete project information including custom fields.

Create a new project. Requires title, board_id, and phase_id. Optionally include description, dates, deals, and labels.

Update an existing project. Provide the project ID and fields to update.

Delete a project by marking it as deleted. This does not permanently remove the project.

Archive a project. Archived projects can be retrieved by using the include_archived filter.

Get all active project phases under a specific board. Returns phases ordered by their order number.

Get details of a specific project phase by ID.

Get all tasks linked to a specific project. Returns task details including assignee and completion status.

Get all activities linked to a specific project. Returns activity details including type, due date, and completion status.

Get project plan showing all tasks and activities with their phases and groups. Returns plan structure.

Update an activity phase or group in a project plan. Allows moving activities between phases and groups.

Update a task phase or group in a project plan. Allows moving tasks between phases and groups.

Get all active groups under a specific project. Returns groups ordered by their order number.

Get all project boards that are not deleted. Returns boards ordered by their order number.

Get details of a specific project board by ID.

List all project templates with cursor-based pagination.

Project templates are reusable blueprints for creating new projects with predefined phases, tasks, and activities.

Workflow tips:

• Templates include project structure (phases, groups, tasks, activities)

• Use templates to standardize project creation across your organization

• Templates can be created from existing projects

• Cursor-based pagination for large template lists

Common use cases:

• List all available templates: {}

• Get templates with custom page size: { "limit": 50 }

• Paginate through templates: { "cursor": "abc123", "limit": 100 }

Example: { "limit": 100 }

Get details of a single project template by ID.

Returns complete information about a project template including its structure, phases, groups, tasks, and activities.

Workflow tips:

• Templates contain the blueprint for creating standardized projects

• Use this to inspect template details before using it to create a project

• Template structure includes phases, task groups, tasks, and activities

• You can create a project from this template using projects/create

Common use cases:

• View template structure before creating a project

• Inspect phases and tasks included in the template

• Review template configuration

• Validate template before use

Example: { "id": 123 }

Get all goals with optional filters.

Retrieves goals based on various filtering criteria including type, title, assignee, and period.

Workflow tips:

• Filter by assignee to see goals for specific users or teams

• Use type.name to filter by goal type (e.g., deals_won, activities_completed)

• Filter by is_active to see only active or inactive goals

• Use period filters to find goals within specific date ranges

Common use cases:

• List all active goals: { "is_active": true }

• Find goals for a user: { "assignee.id": 123, "assignee.type": "person" }

• Filter by goal type: { "type.name": "deals_won" }

Add a new goal to track performance metrics.

Creates a goal with specified type, assignee, expected outcome, and duration. A report is automatically created to track goal progress.

Workflow tips:

• Specify the goal type (e.g., deals_won, activities_completed)

• Assign to a user or team

• Set target value and tracking metric

• Define duration period (start and end dates)

• Choose interval (weekly, monthly, quarterly, yearly)

Common use cases:

• Track deal revenue: type with "deals_won", tracking_metric "sum"

• Track activities: type with "activities_completed", tracking_metric "count"

• Team goals: assignee type "team"

Update an existing goal.

Updates goal properties such as title, type, assignee, expected outcome, duration, or interval.

Workflow tips:

• Use goals/list to find the goal ID first

• Only include fields you want to update

• Changes take effect immediately in goal tracking

Common use cases:

• Adjust target value: { "id": "goal-id", "expected_outcome": { "target": 50000, "tracking_metric": "sum" } }

• Change assignee: { "id": "goal-id", "assignee": { "id": 456, "type": "person" } }

• Update title: { "id": "goal-id", "title": "New Goal Title" }

Delete an existing goal.

Permanently removes a goal. The associated report will also be deleted.

Workflow tips:

• Use goals/list to find the goal ID first

• This action cannot be undone

• Related reports will be removed

Common use cases:

• Remove completed goal: { "id": "goal-id" }

• Clean up old goals: { "id": "goal-id" }

Get the progress and results of a goal for a specified period.

Retrieves goal progress data including current value, target, and completion percentage.

Workflow tips:

• Use goals/list to find the goal ID first

• Specify period.start and period.end to get results for specific timeframe

• Results show progress toward the goal target

• Use to track performance over time

Common use cases:

• Check current goal progress: { "id": "goal-id", "period.start": "2024-01-01", "period.end": "2024-01-31" }

• Monthly goal tracking: Specify start and end of month

• Compare periods: Get results for different date ranges

Get all tasks with optional filters.

Retrieves tasks using cursor-based pagination. Can filter by assignee, project, parent task, and completion status.

Workflow tips:

• Use cursor for pagination through large result sets

• Filter by assignee_id to see tasks for specific users

• Filter by project_id to see project tasks

• Filter by done status (0 = not done, 1 = done)

• Filter by parent_task_id to see subtasks

Common use cases:

• List all incomplete tasks: { "done": 0 }

• Get tasks for a user: { "assignee_id": 123 }

• Get project tasks: { "project_id": 456 }

• Get subtasks: { "parent_task_id": 789 }

Get detailed information about a specific task by ID.

Retrieves complete information about a single task including subject, description, assignee, due date, and completion status.

Workflow tips:

• Use tasks/list to find task IDs first

• Response includes all task details

• Cached for 5 minutes for better performance

Common use cases:

• Get task details: { "id": 123 }

• Check task status before updating

• Retrieve task information for display

Add a new task to a project or as a standalone task.

Creates a task with subject, optional description, assignee, due date, and project association.

Workflow tips:

• Subject is required (task title)

• Assign to a user with assignee_id

• Associate with a project using project_id

• Create subtasks using parent_task_id

• Set due_date for deadline tracking

• Tasks default to not done (done = 0)

Common use cases:

• Create project task: { "subject": "Review proposal", "project_id": 123, "assignee_id": 456 }

• Create subtask: { "subject": "Research options", "parent_task_id": 789 }

• Create with due date: { "subject": "Send report", "due_date": "2024-12-31" }

Update an existing task.

Updates task properties such as subject, description, assignee, due date, or completion status.

Workflow tips:

• Use tasks/list or tasks/get to find the task ID first

• Only include fields you want to update

• Set done = 1 to mark as completed

• Changes take effect immediately

Common use cases:

• Mark as done: { "id": 123, "done": 1 }

• Reassign task: { "id": 123, "assignee_id": 456 }

• Update due date: { "id": 123, "due_date": "2024-12-31" }

• Update subject: { "id": 123, "subject": "Updated Task Title" }

Delete an existing task.

Permanently removes a task from the system.

Workflow tips:

• Use tasks/list to find the task ID first

• This action cannot be undone

• Deleting a parent task may affect subtasks

Common use cases:

• Remove completed task: { "id": 123 }

• Clean up old tasks: { "id": 456 }

Get all activity types.

Retrieves all activity types including both default and custom types. Activity types define the categories of activities that can be created (e.g., call, meeting, task, deadline).

Workflow tips:

• Returns both system-defined and custom activity types

• Use to populate activity type selectors in UI

• Check is_custom_flag to distinguish custom from default types

• Cached for 5 minutes for better performance

Common use cases:

• List all types: {}

• Get activity type options for creating activities

• Check available activity types in the system

Add a new custom activity type.

Creates a custom activity type with specified name, icon, and color. Custom activity types allow you to categorize activities beyond the default types.

Workflow tips:

• Name is required (e.g., "Video Call", "Site Visit")

• Choose an icon_key (e.g., task, call, meeting, deadline, email, lunch, camera)

• Set a color as 6-character hex code without # (e.g., "FF5733")

• Custom types appear alongside default types in activity creation

Common use cases:

• Create "Video Call" type: { "name": "Video Call", "icon_key": "camera", "color": "4A90E2" }

• Create "Site Visit" type: { "name": "Site Visit", "icon_key": "meeting", "color": "E24A4A" }

• Create "Demo" type: { "name": "Demo", "icon_key": "task", "color": "4AE290" }

Update an existing activity type.

Updates activity type properties such as name, icon, color, or display order.

Workflow tips:

• Use activity_types/list to find the activity type ID first

• Only include fields you want to update

• Cannot update system-defined activity types, only custom ones

• Changes affect all activities using this type

Common use cases:

• Change name: { "id": 12, "name": "Video Conference" }

• Update color: { "id": 12, "color": "00FF00" }

• Change icon: { "id": 12, "icon_key": "camera" }

• Update order: { "id": 12, "order_nr": 5 }

Delete an activity type.

Marks an activity type as deleted. Only custom activity types can be deleted, not system-defined ones.

Workflow tips:

• Use activity_types/list to find the activity type ID first

• Only custom activity types can be deleted (is_custom_flag = true)

• Existing activities with this type will retain the type but it won't be available for new activities

• This action marks the type as inactive (active_flag = false)

Common use cases:

• Remove unused custom type: { "id": 12 }

• Clean up old activity types: { "id": 15 }

Delete multiple activity types in bulk.

Marks multiple activity types as deleted in a single operation. Only custom activity types can be deleted.

Workflow tips:

• Provide comma-separated activity type IDs

• Only custom activity types can be deleted (is_custom_flag = true)

• More efficient than deleting one at a time

• All specified types are marked as inactive in one request

Common use cases:

• Remove multiple custom types: { "ids": "12,13,14" }

• Bulk cleanup: { "ids": "15,16,17,18" }

Get all call logs assigned to the current user.

Retrieves call logs with pagination support. Returns logs for phone calls including duration, outcome, and associated records.

Workflow tips:

• Returns call logs for the authenticated user

• Use start and limit for pagination

• Each call log includes phone numbers, duration, outcome, and timestamps

• Can be linked to persons, organizations, deals, and leads

• Cached for 1 minute for better performance

Common use cases:

• List recent calls: { "start": 0, "limit": 50 }

• Paginate through calls: { "start": 50, "limit": 50 }

• Get all call history: Iterate through pages

Get details of a specific call log by ID.

Retrieves complete information about a single call log including phone numbers, duration, outcome, and linked records.

Workflow tips:

• Use call_logs/list to find call log IDs first

• Response includes all call details and associations

• Shows if there is a recording attached (has_recording)

• Cached for 5 minutes for better performance

Common use cases:

• Get call details: { "id": "CAd92b224eb4a39b5ad8fea92ff0e" }

• Check call outcome and duration

• Review call notes and associations

Add a new call log to track phone call activity.

Creates a call log with phone numbers, outcome, duration, and timestamps. Can be linked to persons, organizations, deals, leads, and activities.

Workflow tips:

• to_phone_number, outcome, start_time, and end_time are required

• Outcome describes call result (e.g., connected, no_answer, busy, voicemail)

• Use ISO 8601 format for timestamps

• Link to records using person_id, org_id, deal_id, or lead_id

• Associate with an activity using activity_id

• Add notes for call details

Common use cases:

• Log successful call: { "to_phone_number": "+1234567890", "outcome": "connected", "start_time": "2024-12-10T10:00:00Z", "end_time": "2024-12-10T10:15:00Z" }

• Log missed call: { "to_phone_number": "+1234567890", "outcome": "no_answer", "start_time": "2024-12-10T10:00:00Z", "end_time": "2024-12-10T10:00:30Z" }

• Link to person: Include "person_id": 123

Attach an audio recording file to a call log.

Uploads an audio file and associates it with a call log. The call log will be marked as having a recording.

Workflow tips:

• Call log must already exist (create with call_logs/create first)

• Provide the call log ID and path to the audio file

• File must be a valid audio format

• This is a multipart/form-data upload

• After upload, has_recording will be true for this call log

Common use cases:

• Attach recording after call: { "id": "CAd92b224eb4a39b5ad8fea92ff0e", "file_path": "/path/to/recording.mp3" }

• Add call recording for documentation

• Store call audio for quality assurance

Delete a call log.

Permanently removes a call log from the system. If there is an audio recording attached, it will also be deleted. Note: The related activity will NOT be removed by this operation.

Workflow tips:

• Use call_logs/list to find the call log ID first

• Deleting the call log also deletes any attached audio recording

• The associated activity (if any) remains in the system

• This action cannot be undone

Common use cases:

• Remove incorrect call log: { "id": "CAd92b224eb4a39b5ad8fea92ff0e" }

• Clean up old call logs: { "id": "CAd92b224eb4a39b5ad8fea92ff0e" }

Get mail threads in a specified folder ordered by the most recent message within.

Get details of a specific mail thread by ID.

Get all mail messages inside a specific mail thread.

Update the properties of a mail thread.

Mark a mail thread as deleted.

Get details of a specific mail message by ID.

Get all teams within the company.

Get details of a specific team by ID.

Add a new team to the company.

Update the properties of a team.

Get all users in a team.

Add a user to a team.

Remove a user from a team.

Get all teams that a specific user belongs to.

Get all relationships for a specific organization.

Get details of a specific organization relationship by ID.

Create a new organization relationship.

Update the properties of an organization relationship.

Delete an organization relationship.

List all permission sets within the company.

Returns all permission sets with their configurations, including admin and regular user sets across different apps.

Workflow tips:

• Permission sets define user access and capabilities

• Apps include: sales, global, account_settings

• Each set has a type (admin, regular, custom)

• Shows assignment counts for each set

• Cached for 15 minutes (permission sets rarely change)

Common use cases:

• List all permission sets: {}

• Filter by app: { "app": "sales" }

• View global permissions: { "app": "global" }

• Check account settings access: { "app": "account_settings" }

Get detailed information about a specific permission set by ID.

Retrieves complete information about a single permission set including its contents (individual permissions).

Workflow tips:

• Use permission_sets/list to find permission set IDs first

• Response includes detailed permission contents

• Shows which specific capabilities are granted

• Cached for 15 minutes for better performance

Common use cases:

• Get permission set details: { "id": "f07d229d-088a-4144-a40f-1fe64295d180" }

• View permission contents and capabilities

• Check what actions a permission set allows

Get permission set assignments.

Returns all users assigned to a specific permission set with pagination support.

Workflow tips:

• Shows all users with this permission set

• Use pagination for permission sets with many users

• Useful for auditing permission set membership

• Helps understand who has access to what

• Cached for 15 minutes

Common use cases:

• Get assignments: { "id": "f07d229d-088a-4144-a40f-1fe64295d180" }

• Paginated list: { "id": "f07d229d-088a-4144-a40f-1fe64295d180", "start": 0, "limit": 50 }

• Audit user permissions and access levels

Create a new messaging channel in Pipedrive. Only admins are able to register new channels.

This endpoint requires the Messengers integration OAuth scope and the Messaging manifest ready for the Messaging app extension.

Required fields:

• name: Name of the channel

• provider_channel_id: ID of the channel in the provider system

Optional fields:

• avatar_url: Avatar URL for the channel

• template_support: Whether the channel supports message templates (default: false)

• provider_type: Type of messaging provider (other, facebook, instagram, whatsapp, telegram, line, viber) (default: other)

Example: { "name": "My Channel", "provider_channel_id": "e283f878-7ef9-4294-8e5c-04a7d003fd92", "avatar_url": "http://my-domain.com/images/test.png", "template_support": false, "provider_type": "whatsapp" }

Delete an existing messenger's channel and all related entities (conversations and messages).

This endpoint requires the Messengers integration OAuth scope and the Messaging manifest ready for the Messaging app extension.

Warning: This action cannot be undone. The channel and all related conversations and messages will be permanently deleted.

Required fields:

• id: The ID of the channel provided by the integration

Example: { "id": "e283f878-7ef9-4294-8e5c-04a7d003fd92" }

Add an incoming message to a conversation in Pipedrive.

This endpoint requires the Messengers integration OAuth scope and the Messaging manifest ready for the Messaging app extension.

Required fields:

• id: ID of the message

• channel_id: ID of the channel the message was sent to

• sender_id: ID of the message sender

• conversation_id: ID of the conversation this message belongs to

• message: Content of the message

• status: Status of the message (e.g., sent, delivered, read)

• created_at: When the message was created (ISO 8601 format)

Optional fields:

• reply_by: When a reply is expected by (ISO 8601 format)

• conversation_link: Link to the conversation in the provider system

• attachments: Array of message attachments

Example: { "id": "e283f878-7ef9-4294-8e5c-04a7d003fd92", "channel_id": "a8aa4db0-91bb-4e90-b9c0-0c6291307e2f", "sender_id": "5d4bd467-d847-4088-ae43-0c7614233bab", "conversation_id": "063ffa46-831c-4027-a04c-b65e17f077b7", "message": "This is a message", "status": "sent", "created_at": "2022-03-01T07:58:35.449Z", "reply_by": "2022-03-01T07:58:35.449Z", "conversation_link": "http://my-server.com/conversations/063ffa46-831c-4027-a04c-b65e17f077b7", "attachments": [ { "id": "b0369d1d-6b6a-4293-88b9-e2924782d47e", "type": "image/png", "name": "Image Name", "size": 600, "url": "http://my-server.com/images/b0369d1d-6b6a-4293-88b9-e2924782d47e.png", "preview_url": "http://my-server.com/images/b0369d1d-6b6a-4293-88b9-e2924782d47e.preview.png" } ] }

Delete an existing conversation from a channel.

This endpoint requires the Messengers integration OAuth scope and the Messaging manifest ready for the Messaging app extension.

Warning: This action cannot be undone. The conversation and all its messages will be permanently deleted.

Required fields:

• channel_id: ID of the channel

• conversation_id: ID of the conversation to delete

Example: { "channel_id": "e283f878-7ef9-4294-8e5c-04a7d003fd92", "conversation_id": "063ffa46-831c-4027-a04c-b65e17f077b7" }

Link a user with the installed video call integration.

Creates a connection between a Pipedrive user and a video calling app provider. This must be called after a user installs the video calling app so that the user's information is sent to Pipedrive.

Required fields:

• user_provider_id: UUID linking the user to the integration

• user_id: ID of the Pipedrive user

• company_id: ID of the company

• marketplace_client_id: Marketplace client identifier

Workflow tips:

• This endpoint is typically called by video calling providers

• The link allows the user to access video calling features within Pipedrive

• All four parameters are required for successful linking

• Returns success message when link is created

Common use cases:

• Initial setup: { "user_provider_id": "1e3943c9-6395-462b-b432-1f252c017f3d", "user_id": 123, "company_id": 456, "marketplace_client_id": "57da5c3c55a82bb4" }

• Enable video calling features for a new user

• Connect user account after OAuth flow

Delete the link between a user and the installed video call integration.

Removes the connection between a Pipedrive user and a video calling app provider. After deletion, the user will no longer have access to the video calling integration features.

Required fields:

• id: UUID of the link to delete

Workflow tips:

• Use this when a user uninstalls the video calling app

• The ID is the same user_provider_id used when creating the link

• Deletion is immediate and cannot be undone

• User must re-link if they want to use the integration again

Common use cases:

• Remove integration: { "id": "1e3943c9-6395-462b-b432-1f252c017f3d" }

• User uninstalls app

• Disable video calling features for a user

• Clean up after removing user access