List deals with pagination and filtering options.

Returns a paginated list 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 'all_not_deleted' deals

• Set owned_by_you=1 to see only your deals

• Combine with filter_id to use pre-configured Pipedrive filters

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

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

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 }

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

Automatically fetch ALL deals with pagination handling.

This tool automatically handles 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 start/limit - pagination is automatic

• Best for exports, reports, or comprehensive analysis

Common use cases:

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

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

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

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.

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.

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.

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"}]

• 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"} ] }

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"}]

• 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).

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.

Get details of a specific organization by ID.

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

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" }