Pipedrive

1. Overview

Pipedrive is a cloud-based Customer Relationship Management (CRM) tool designed to help sales teams manage their sales pipeline, track leads, and close deals more effectively. It provides a visual interface for managing contacts, organizations, activities, and sales opportunities.

With the GoInsight Pipedrive node, you can seamlessly integrate your sales and customer management processes into your automated workflows. This allows you to perform a wide range of operations to manage your CRM data programmatically, including:

• Deal Management: Create, update, delete, search, and retrieve sales deals. You can also manage the products associated with each deal.
• Contact and Organization Management: Create, update, delete, and search for persons and organizations to keep your contact database current.
• Activity and Communication Tracking: Log new activities, create notes, and upload files, associating them with specific deals, persons, or organizations.
• Lead Management: Capture and manage new leads from various sources directly within your workflows.

2. Prerequisites

Before using this node, you need to have a valid Pipedrive account. Depending on your organization's security settings, you may need administrator privileges to generate an API token for authentication.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on the following resources: Activity, Deal, Deal Product, File, Lead, Note, Organization, Person, and Product.

Operation Details

Create an Activity

Creates a new PipeDrive activity record. Core required field: Subject. Commonly used optional fields: Type, DueDate, DueTime. Advanced options (for linking): DealId, PersonId, OrgId. Additional info: Duration, Note. WARNING: This action does not support idempotency — if the request times out and is retried, duplicate activities may be created. Consider using a unique identifier in Subject for deduplication. NOTE: This workflow has 9 non-credential input parameters which exceeds the recommended limit of 8; all fields are kept because each serves a distinct scheduling or association purpose. Don't use when: modifying an existing record → use the corresponding Update action instead. Side effects: creates a permanent record; NOT idempotent — calling twice creates two records.

Input Parameters:

• Subject: Activity subject/title (required). Example: "Follow-up call with John Doe"

Options:

• Confirm: ⚠️ Safety gate: Must be explicitly set to true to execute this CREATE operation. Prevents accidental duplicate creation during Agent retries. If false or omitted, returns StatusCode=-1.
• Type: Activity type key (optional). Common values: call (phone call, sales follow-up), meeting (client visit, team sync), email (proposal, quotation), task (internal action item), deadline (contract expiry, payment due), lunch (relationship building). Use your Pipedrive account's configured activity types. Example: "call"
• DueDate: Activity due date in YYYY-MM-DD format (optional). Example: "2024-02-15"
• DueTime: Activity due time in 24-hour HH:MM format (optional). Example: "14:30" (means 2:30 PM)
• DealId: ID of the deal to associate with this activity (optional). Obtain via Search Deals or Get Deals action. Example: "789"
• PersonId: ID of the person/contact to associate with this activity (optional). Obtain via Search Persons or Get Persons action. Example: "123"
• OrgId: ID of the organization to associate with this activity (optional). Obtain via Search Organizations or Get Organizations action. Example: "456"
• AdditionalFields: Additional activity fields as a JSON object (optional). Supported fields:
• note (string): activity note/comment. Example: "Follow up on Q1 contract renewal"
• duration (number or string): activity duration in minutes, must be 0 or greater. Example: 30

Example: {"note": "Follow up on Q1 contract renewal", "duration": 30}

Output:

• ActivityId (string): The ID of the created activity
• Type (string): The type/category of the created activity
• Subject (string): The subject/title of the created activity
• DueDate (string): The due date of the activity
• DueTime (string): The due time of the activity
• Duration (string): The duration of the activity in minutes
• Done (string): ⚠️ STRING-ENCODED BOOLEAN: Returns "true" or "false" as a string (not native boolean). Whether the activity is marked as done. Newly created activities default to "false". To check completion in downstream logic, use string comparison: Done == "true".
• DealId (string): The ID of the associated deal
• PersonId (string): The ID of the associated person
• PersonName (string): The name of the associated person
• OrgId (string): The ID of the associated organization
• OrgName (string): The name of the associated organization
• CreatedTime (string): The timestamp when the activity was created
• UpdateTime (string): The timestamp when the activity was last updated
• Note (string): The note/comment attached to the activity
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Delete an Activity

WARNING: Permanently deletes a PipeDrive activity record. This operation CANNOT BE UNDONE. Use with caution. Don't use when: archiving or closing a deal (use Update with Status field instead). Side effects: PERMANENTLY deletes the record; this action cannot be undone. Requires Confirm=true.

Input Parameters:

• ActivityId: Numeric activity ID to delete (required). Obtain via Get Activities or Search Activities action. WARNING: Deletion is permanent and cannot be undone. Example: "101"

Options:

• Confirm: ⚠️ SAFETY GATE: Must be explicitly set to true to proceed with deletion. This operation is PERMANENT and CANNOT BE UNDONE. Prevents accidental deletion by Agent hallucinations or misunderstandings. Set to false to abort.

Output:

• ActivityId (string): The ID of the deleted activity
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error). Use for debugging.
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Get Activities

Retrieves multiple PipeDrive activity records by IDs. Supports batch operations with detailed success and failure reporting including 207 partial success status codes. Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Input Parameters:

• ActivityIds: Comma-separated list of activity IDs to retrieve (required, max 50 IDs). Obtain the ActivityId field from Search Activities action results. Both English comma (,) and Chinese comma (，) are supported. Example: "101,102,103"

Output:

• Activities (object-array): Array of activity objects. Each object contains: ActivityId (string), Subject (string), Type (string: call/meeting/task/deadline/email/lunch), DueDate (string: YYYY-MM-DD), DueTime (string: HH:MM, 24-hour), Duration (string: minutes), Done (string: "true" or "false"), DealId (string: empty if not linked), DealTitle (string), PersonId (string: empty if not linked), PersonName (string), OrgId (string: empty if not linked), OrgName (string), OwnerId (string), OwnerName (string), CreatedTime (string: YYYY-MM-DD HH:MM:SS), UpdateTime (string: YYYY-MM-DD HH:MM:SS), Note (string: activity notes)
• SuccessCount (number): Number of activities successfully retrieved (integer)
• FailedItems (object-array): Array of failure objects for IDs that could not be retrieved. Each object contains: ActivityId (string: the ID that failed), StatusCode (number: HTTP status code, e.g. 404=not found, 401=unauthorized), ErrorMessage (string: reason for failure)
• TotalRequested (number): Total number of activity IDs requested (integer)
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): First non-200 HTTP status code encountered during batch retrieval, or 200 if all succeeded. 0 if request never reached the server (e.g. parameter validation failed). For debugging purposes.
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Search Activities

Searches for PipeDrive activities using filter criteria like deal_id, person_id, org_id, or user_id with cursor-based pagination. Don't use when: you already have a specific ID → use the corresponding Get action directly for better performance. Side effects: read-only, no data is modified.

Options:

• DealId: Deal ID to filter activities associated with a specific deal (optional). Obtain via Search Deal or Get Deals action. Example: "789"
• PersonId: Person ID to filter activities associated with a specific person (optional). Obtain via Search Persons action. Example: "123"
• OrgId: Organization ID to filter activities (optional). Obtain via Search Organizations action. Example: "456"
• UserId: User ID to filter activities owned by a specific user (optional). Obtain via user listing. Example: "1"
• Done: Activity completion status filter. Values: "0" (incomplete activities only), "1" (completed activities only), "" (all activities). Example: "0"
• Limit: Maximum number of activities to return (default 10, max 500)
• Cursor: Pagination cursor for next page (empty string for first page). Get from NextCursor in previous response.

Output:

• Activities (object-array): Array of matching activity objects. Each object contains: ActivityId, Subject, Type, DueDate, DueTime, Duration, Done, DealId, DealTitle, PersonId, PersonName, OrgId, OrgName, OwnerId, OwnerName, CreatedTime, UpdateTime, Note.
• NextCursor (string): Cursor for next page (empty if no more results)
• CurrentCount (number): Number of results in current page
• TotalCount (number): Total number of activities found
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Update an Activity

Updates a single PipeDrive activity record with the specified activity ID and optional field updates. At least one update field must be provided. Don't use when: creating a new record → use the corresponding Create action. Side effects: modifies existing record using PATCH (incremental); only provided fields are changed, others retain their original values.

Input Parameters:

• ActivityId: The ID of the activity to update (required). Obtain via Search Activities or Get Activities action. Example: "123"

Options:

• Subject: New activity subject/title (optional). Example: "Follow-up call with client"
• DueDate: New due date for the activity (optional). Format: YYYY-MM-DD. Example: "2024-01-15"
• DueTime: New due time for the activity (optional). Format: HH:MM (24-hour). Example: "14:30"
• Duration: Activity duration in minutes (optional, must be >= 0). Example: 30
• Done: Whether the activity is completed (optional). Example: false
• Note: Notes or additional details for the activity (optional). Example: "Discuss Q1 contract renewal"

Output:

• ActivityId (string): The ID of the updated activity
• Type (string): The type/category of the activity (e.g., call, meeting, task, deadline, email, lunch)
• Subject (string): The subject/title of the activity
• DueDate (string): The due date of the activity
• DueTime (string): The due time of the activity
• Duration (string): The duration of the activity in minutes
• Done (string): Whether the activity is marked as done. Returns "true" or "false" as a string (not boolean). Newly created activities default to "false".
• DealId (string): The ID of the associated deal
• PersonId (string): The ID of the associated person
• PersonName (string): The name of the associated person
• OrgId (string): The ID of the associated organization
• OrgName (string): The name of the associated organization
• CreatedTime (string): The timestamp when the activity was created
• UpdateTime (string): The timestamp when the activity was last updated
• Note (string): The note/comment attached to the activity
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Create a Deal

Creates a new PipeDrive deal with the specified title and optional parameters. Parameter priority: StageId takes precedence over PipelineId when both are provided (stage determines the pipeline). PersonId and OrgId can be set independently or together. Use AdditionalFields for probability, visible_to, user_id, and other Pipedrive deal fields not covered by named parameters. Don't use when: modifying an existing record → use the corresponding Update action instead. Side effects: creates a permanent record; NOT idempotent — calling twice creates two records.

Input Parameters:

• Title: The title/name of the deal (required). A clear, descriptive title. Example: "Acme Corp Q3 Software License Deal"

Options:

• PersonId: Associated person ID (optional, 0 = not set). Obtain via Search Persons or Get Persons action.
• OrgId: Associated organization ID (optional, 0 = not set). Obtain via Search Organizations or Get Organizations action.
• Value: Deal monetary value (optional, 0 = not set). Must be >= 0. Supports decimals. Example: 50000 or 50000.50
• Currency: ISO 4217 three-letter currency code (default: USD). Example: USD, EUR, GBP
• StageId: Deal stage ID (optional, 0 = not set). Represents the sales stage within the pipeline (e.g. Qualified, Proposal Sent, Negotiation). Must belong to the pipeline specified in PipelineId. Obtain via Get Stages action.
• PipelineId: Sales pipeline ID (optional, 0 = uses default pipeline). A pipeline is a sequence of stages that deals move through (e.g. New Business, Renewal). Obtain via Get Pipelines action.
• ExpectedCloseDate: Expected close date of the deal (optional). Format: YYYY-MM-DD. Example: 2024-12-31
• AdditionalFields: Additional deal fields as a JSON object (optional). Supports: probability (number: 0-100, win probability %), visible_to (number: 1=owner only, 3=entire company), user_id (number: deal owner user ID), and other valid Pipedrive deal fields. Example: {"probability": 75, "visible_to": 3}

Output:

• DealId (string): The ID of the created deal
• Title (string): The title of the created deal
• Value (string): The monetary value of the created deal
• Currency (string): The currency code of the deal
• Status (string): Deal status. Possible values: open (active/in-progress), won (successfully closed), lost (lost or cancelled), deleted (removed). This is a complete enumeration.
• PersonId (string): The ID of the associated person
• PersonName (string): The name of the associated person
• OrgId (string): The ID of the associated organization
• OrgName (string): The name of the associated organization
• StageId (string): The ID of the deal stage
• StageName (string): The name of the deal stage
• PipelineId (string): The ID of the sales pipeline
• PipelineName (string): The name of the sales pipeline
• ExpectedCloseDate (string): Expected close date of the deal in YYYY-MM-DD format
• CreatedTime (string): The timestamp when the deal was created
• UpdateTime (string): The timestamp when the deal was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Delete a Deal

WARNING: Permanently deletes a PipeDrive deal record. This operation CANNOT BE UNDONE. The deal and all associated data will be irreversibly removed from the system. Use with caution. Don't use when: archiving or closing a deal (use Update with Status field instead). Side effects: PERMANENTLY deletes the record; this action cannot be undone. Requires Confirm=true.

Input Parameters:

• DealId: Numeric deal ID to delete (required). Obtain via Search Deals or Get Deals action. WARNING: Deletion is permanent and cannot be undone. Example: "789"

Options:

• Confirm: ⚠️ SAFETY GATE: Must be explicitly set to true to proceed with deletion. This operation is PERMANENT and CANNOT BE UNDONE. Prevents accidental deletion by Agent hallucinations or misunderstandings. Set to false to abort.

Output:

• DealId (string): The ID of the deleted deal
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error). Use for debugging.
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Duplicate a Deal

Duplicates a PipeDrive deal record by ID. Creates a copy with an optional new title. Don't use when: modifying an existing deal → use Update_a_Deal. Side effects: creates a new deal record; NOT idempotent — calling twice creates two deals. What IS copied: core deal fields (title, value, currency, pipeline, stage, owner, associated person/org). What is NOT copied: activities, notes, files, email threads, and other associated records. PipeDrive automation workflows (if enabled) may be triggered for the new deal.

Input Parameters:

• DealId: Numeric deal ID to duplicate (required). Obtain via Search Deal or Get Deals action. Example: "789"

Options:

• Title: New deal title (optional). If not provided, system appends " (Copy)" to the original title. Example: "Q1 Enterprise Deal - Copy"

Output:

• DealId (string): The ID of the duplicated deal (numeric string)
• Title (string): The title of the duplicated deal
• PersonId (string): The ID of the associated person
• PersonName (string): The name of the associated person
• OrganizationId (string): The ID of the associated organization
• OrganizationName (string): The name of the associated organization
• StageId (string): The ID of the deal stage
• StageName (string): The name of the deal stage
• PipelineId (string): The ID of the pipeline
• PipelineName (string): The name of the pipeline
• Value (string): The value amount of the deal. Returned as a string (e.g. "50000.0"); convert to float if arithmetic is needed.
• Currency (string): The currency of the deal
• OwnerId (string): The ID of the deal owner
• OwnerName (string): The name of the deal owner
• Status (string): The status of the duplicated deal. Possible values: "open" (active, in progress), "won" (closed and won), "lost" (closed and lost), "deleted" (soft-deleted, can be restored).
• CreatedTime (string): The timestamp when the deal was created. Format: YYYY-MM-DD HH:MM:SS (UTC).
• UpdateTime (string): The timestamp when the deal was last updated. Format: YYYY-MM-DD HH:MM:SS (UTC).
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from Pipedrive API (0 if network error before reaching server)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Get Deals

Retrieves one or more PipeDrive deal records specified by their deal IDs. Supports batch retrieval with comma-separated IDs and returns data as JSON string arrays. Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Input Parameters:

• DealId: Deal ID or comma-separated list of deal IDs to retrieve (required, max 50 IDs). Obtain from the DealId field returned by 'Search Deal' action. Both English comma (,) and Chinese comma (，) are supported. Single: "789". Multiple: "789,790,791".

Output:

• Deals (object-array): Array of deal objects successfully retrieved. Each object contains:

Core Fields:

• DealId (string): Unique deal identifier
• Title (string): Deal name/title
• Value (string): Numeric deal amount (e.g. "50000.0")
• Currency (string): ISO 4217 currency code. Common values: USD (US Dollar), EUR (Euro), GBP (British Pound), CNY (Chinese Yuan), JPY (Japanese Yen)
• Status (string): Deal status. Values: open=active in pipeline; won=successfully closed, revenue counted; lost=lost or cancelled, no revenue; deleted=archived (soft-deleted), can be restored by admin

Contact & Organization:

• PersonId (string): Associated contact ID (empty if no contact linked)
• PersonName (string): Contact name
• OrgId (string): Associated organization ID (empty if no org linked)
• OrgName (string): Organization name

Pipeline Info:

• StageId (string): Current stage ID
• StageName (string): Current stage name
• PipelineId (string): Pipeline ID
• PipelineName (string): Pipeline name

Timestamps:

• CreatedTime (string): Creation time (YYYY-MM-DD HH:MM:SS)
• UpdateTime (string): Last update time (YYYY-MM-DD HH:MM:SS)
• WonTime (string): Won timestamp (empty if not won)
• LostTime (string): Lost timestamp (empty if not lost)
• ExpectedCloseDate (string): Expected close date (YYYY-MM-DD, empty if not set)
• FailedItems (object-array): Array of failure objects for deal IDs that could not be retrieved. Each object contains:
• DealId (string): The deal ID that failed
• StatusCode (number): HTTP status code for this specific failure (e.g. 404=not found, 401=unauthorized)
• ErrorMessage (string): Detailed reason for failure

Example: [{"DealId": "790", "StatusCode": 404, "ErrorMessage": "Deal not found"}]

• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): First non-200 HTTP status code encountered during batch retrieval, or 200 if all requests succeeded. 0 if request never reached the server.
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Search Deal

Searches PipeDrive deal records by keyword with cursor-based pagination. Supports fuzzy (default) and exact matching. First request: leave Cursor empty. Next page: pass NextCursor from previous response. Check HasNextPage to determine if more results exist. Results include relevance scoring (ResultScore). Don't use when: you already have a specific ID → use the corresponding Get action directly for better performance. Side effects: read-only, no data is modified.

Input Parameters:

• SearchTerm: Search keyword to find deals (required, minimum 2 characters). Supports fuzzy/partial matching. Can be deal title, company name, or contact name. Example: "Enterprise License"

Options:

• Limit: Number of results to return per page (1-500, default 50). Example: 10
• Cursor: Pagination cursor for fetching the next page of results. Leave empty for the first request. Copy the NextCursor value from the previous response to get the next page. Think of it as a bookmark that marks where the last query stopped. Example: "eyJpZCI6MTIzNDU2fQ=="
• ExactMatch: Search matching mode. false (default) = fuzzy search, matches partial text (e.g. "Acme" matches "Acme Corp"). true = exact match only. Use false for most searches to get broader results.

Output:

• SearchTerm (string): The search term used to find deals
• ReturnedCount (number): Number of deals returned in this search response
• NextCursor (string): Cursor for the next page (empty if no next page). Pass to Cursor in the next call.
• HasNextPage (bool): Whether there are more results available
• Deals (object-array): Array of found deal objects. Each object contains: DealId (string, use with Get Deals/Update a Deal/Delete a Deal), Title (string), Value (string), Currency (string), Status (string: open/won/lost), PersonName (string), OrgName (string), StageName (string), PipelineName (string), CreatedTime (string: YYYY-MM-DD HH:MM:SS), UpdateTime (string: YYYY-MM-DD HH:MM:SS), ResultScore (string: relevance score 0-1).
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Update a Deal

Updates a PipeDrive deal record with new details. Update Strategy: PATCH (Partial Update) — only the fields you provide will be updated; fields left empty will retain their original values. This is NOT a full replacement (PUT). NOTE: This workflow has 9 non-credential input parameters (DealId, Title, Value, Currency, StageId, PersonId, OrganizationId, OwnerId, Status), which exceeds the recommended limit of 8. Consider moving less-common fields (e.g. Currency, OwnerId) to an AdditionalFields pattern if the UI imposes a hard limit. Don't use when: creating a new record → use the corresponding Create action. Side effects: modifies existing record using PATCH (incremental); only provided fields are changed, others retain their original values.

Input Parameters:

• DealId: The ID of the deal to update (required). Obtain via Search Deals or Get Deals action. Example: "789"

Options:

• Title: New deal title (optional). Example: "Enterprise Software Deal"
• Value: New deal value (optional). Plain number without currency symbols or thousand separators. Example: "50000" or "50000.50"
• Currency: Deal currency (optional). 3-letter currency code (ISO 4217 standard). Common values: USD (US Dollar), EUR (Euro), GBP (British Pound), CNY (Chinese Yuan). Example: "USD"
• StageId: Stage ID to move the deal to (optional). A stage represents the current phase in your sales process (e.g., "Proposal Sent", "Negotiation", "Closed Won"). Each pipeline has multiple stages. Obtain via pipeline/stages listing. Example: "2"
• PersonId: Associated contact person ID (optional). Obtain via Search Persons or Get Persons action. Example: "123"
• OrganizationId: Associated organization ID (optional). Obtain via Search Organizations action. Example: "456"
• OwnerId: Deal owner (user) ID (optional). Obtain via Get Users action. Example: "1"
• Status: Deal status (optional). Valid values: open (active and in progress), won (successfully closed), lost (deal lost to competitor or cancelled), deleted (soft delete — deal is hidden from views but can be restored by admin; data is NOT permanently removed). Example: "open"

Output:

• DealId (string): The ID of the updated deal
• Title (string): The title of the updated deal
• PersonId (string): The ID of the associated person
• PersonName (string): The name of the associated person
• OrganizationId (string): The ID of the associated organization
• OrganizationName (string): The name of the associated organization
• StageId (string): The ID of the deal stage
• StageName (string): The name of the deal stage
• PipelineId (string): The ID of the pipeline
• PipelineName (string): The name of the pipeline
• Value (string): The value of the deal
• Currency (string): The currency of the deal
• OwnerId (string): The ID of the deal owner
• OwnerName (string): The name of the deal owner
• Status (string): The status of the deal
• CreatedTime (string): The timestamp when the deal was created
• UpdateTime (string): The timestamp when the deal was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Add a Deal Product

Adds a product to a PipeDrive deal with specified pricing, quantity, and optional discount and tax parameters. Creates a product attachment to the deal and returns detailed product attachment information.

⚠️ Idempotency Note: This action does NOT check for duplicate products. If the same product is added multiple times (e.g., due to network retry), multiple product attachments will be created. Call 'Get Deal Products' first to verify the product is not already attached. Don't use when: modifying an existing record → use the corresponding Update action instead. Side effects: creates a permanent record; NOT idempotent — calling twice creates two records.

Input Parameters:

• DealId: The ID of the deal to add the product to (required). Obtain via Search Deals or Get Deals action. Example: "789"
• ProductId: The ID of the product to add (required). Obtain via Get Products action. Example: "501"
• ItemPrice: Unit price before tax and discount (required). Must be >= 0. Example: 999.99

Options:

• Quantity: Number of product units. Must be > 0. Default: 1. Example: 2
• Discount: Fixed discount amount in currency units (NOT a percentage) deducted from the total. Must be >= 0. Default: 0. Formula: Sum = (ItemPrice × Quantity) + Tax - Discount. Example: to give a $50 discount enter 50.0 (not 0.5 or 5%)
• Tax: Fixed tax amount in currency units (NOT a tax rate) added to the subtotal. Must be >= 0. Default: 0. Formula: Sum = (ItemPrice × Quantity) + Tax - Discount. Example: if tax is $79.99 enter 79.99 (not 0.08 for 8% tax rate)
• Comments: Optional comments about the product attachment. Example: "Annual subscription license"

Output:

• ProductAttachmentId (string): The ID of the created product attachment
• DealId (string): The ID of the deal the product was added to
• ProductId (string): The ID of the added product
• ProductName (string): The name of the added product
• ItemPrice (string): The price per unit of the product
• Quantity (string): The quantity of the product added
• Discount (string): The fixed discount amount (in currency units) applied to the product
• Tax (string): The fixed tax amount (in currency units) applied to the product
• Sum (string): The total amount for this product (price * quantity + tax - discount)
• Currency (string): The currency code for the product pricing (ISO 4217 three-letter code, e.g., USD, EUR, CNY). Inherited from the deal's currency setting.
• Comments (string): Comments about the product attachment
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by the Pipedrive API. Default 0 means the request never reached the server (e.g., timeout or network error). Use for debugging.
• StatusCode (number): Operation status code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Deal Products

Retrieves products associated with a PipeDrive deal. Returns detailed product information and total value. Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Input Parameters:

• DealId: Numeric deal ID to get products for (required). Obtain the DealId field from the 'Search Deal' or 'Get Deals' action (exact tool names in PipeDrive integration). Example: "789"

Options:

• IncludeProductData: Whether to return extended product details (optional, string enum, default: "1"). "1" = include extra product fields (ProductCode, ProductDescription, ProductUnit, ProductTax, ProductCategory, ProductActiveFlag) — useful for inventory management and reporting. "0" = basic fields only (faster response) — sufficient for simple deal value calculations. Example: "1"

Output:

• Products (object-array): Array of product objects associated with the deal. Each object contains: Id (product attachment record ID), DealId, ProductId (catalog product ID), ProductName, ItemPrice (unit price), Quantity, Sum (ItemPrice × Quantity), Currency (ISO code, e.g. USD), Comments, EnabledFlag ("1"=active, "0"=inactive), AddTime (YYYY-MM-DD HH:MM:SS). When IncludeProductData="1", also includes: ProductCode, ProductDescription, ProductUnit, ProductTax, ProductCategory, ProductActiveFlag ("1"=catalog product active, "0"=inactive).
• ProductCount (number): Total number of products in the deal
• TotalValue (number): Total value of all products in the deal (sum of all Sum fields)
• DealId (string): Deal ID as provided in the request (string). Example: "789"
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Remove a Deal Product

Removes a specific product attachment from a PipeDrive deal by product attachment ID. This operation permanently deletes the product-deal association and cannot be undone. Don't use when: updating a product in a deal → use Update_a_Deal_Product. Side effects: permanently removes the product association from the deal.

Input Parameters:

• Confirm: ⚠️ Safety gate: Must be explicitly set to true to execute this DELETE operation. Prevents accidental removal during Agent retries. If false or omitted, returns StatusCode=-1.
• DealId: The ID of the deal to remove the product from (required). Obtain via Search Deal or Get Deals action. Example: "789"
• ProductAttachmentId: The ID of the product attachment to remove (required). This is NOT the product ID itself, but the attachment ID linking the product to this specific deal. Obtain via Get Deal Products action. Example: "601"

Output:

• DealId (string): The ID of the deal the product was removed from
• ProductAttachmentId (string): The ID of the removed product attachment
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Update a Deal Product

⚠️ At least one optional field (ItemPrice, Quantity, Discount, Tax, or Comments) must be provided. Updates an existing product attachment on a PipeDrive deal with new pricing, quantity, discount, tax, and comment information. Only the provided fields will be updated, allowing partial updates of product details. Don't use when: creating a new record → use the corresponding Create action. Side effects: modifies existing record using PATCH (incremental); only provided fields are changed, others retain their original values.

Input Parameters:

• DealId: The ID of the deal containing the product (required). Obtain from the DealId output field of Get Deals or Search Deals action. Example: "789"
• ProductAttachmentId: The ID of the product attachment to update (required). A product attachment represents a product added to a deal in PipeDrive. Obtain from the ProductAttachmentId output field of Get Deal Products or Add a Deal Product action. Example: "601"

Options:

• ItemPrice: New price per unit of the product (optional, must be >= 0). Example: 1199.99
• Quantity: New number of product units (optional, must be > 0). Example: 2
• Discount: New discount amount to apply (optional, must be >= 0). Example: 100
• Tax: New tax amount to apply (optional, must be >= 0). Example: 0
• Comments: New comments about the product attachment (optional). Example: "Renewed at discounted rate"

Output:

• ProductAttachmentId (string): The ID of the updated product attachment. A product attachment represents a product added to a deal in PipeDrive.
• DealId (string): The ID of the deal containing the updated product
• ProductId (string): The ID of the updated product
• ProductName (string): The name of the updated product
• ItemPrice (number): The updated price per unit of the product
• Quantity (number): The updated quantity of the product
• Discount (number): The updated discount amount applied to the product
• Tax (number): The updated tax amount applied to the product
• Sum (number): The updated total amount for this product, calculated by PipeDrive based on ItemPrice, Quantity, Discount, and Tax.
• Currency (string): The currency code for the product pricing
• Comments (string): The updated comments about the product attachment
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success. Examples: "Re-authorize the credential and retry." (401/403), "Resource not found. Verify the ID is correct." (404), "Rate limit exceeded. Retry after a short delay." (429).
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Create a File

Upload a file to PipeDrive and attach it to a business entity (Deal/Person/Organization/Product/Activity/Lead). Common use cases: attach contract PDF to a deal, upload invoice to an organization, associate meeting notes with a person. IMPORTANT: Must provide at least one entity ID (DealId/PersonId/OrgId/ProductId/ActivityId/LeadId) to associate the file with. Don't use when: modifying an existing record → use the corresponding Update action instead. Side effects: creates a permanent record; NOT idempotent — calling twice creates two records.

Input Parameters:

• FileName: File name with extension (required). Example: "contract.pdf", "report.xlsx"
• FileContent: File content in Base64 format (required). Convert your file to Base64 text before passing. Python: base64.b64encode(open("file","rb").read()).decode("utf-8"). CLI: base64 -i yourfile.pdf. Must be a complete Base64 string with no line breaks. Example: "SGVsbG8sIFBpcGVkcml2ZSEgVGhpcyBpcyBhIHNhbXBsZSB0ZXh0IGZpbGUu"

Options:

• DealId: The numeric ID of the deal to associate this file with (optional, but at least one entity ID required). Obtain via Search Deals or Get Deals action. Example: "789"
• PersonId: The numeric ID of the person to associate this file with (optional, but at least one entity ID required). Obtain via Search Persons or Get Persons action. Example: "123"
• OrgId: The numeric ID of the organization to associate this file with (optional, but at least one entity ID required). Obtain via Search Organizations or Get Organizations action. Example: "456"
• ProductId: The numeric ID of the product to associate this file with (optional, but at least one entity ID required). Obtain via Get Products action. Example: "501"
• ActivityId: The numeric ID of the activity to associate this file with (optional, but at least one entity ID required). Obtain via Get Activities or Search Activities action. Example: "88"
• LeadId: The ID of the lead to associate this file with (optional, but at least one entity ID required). Obtain via Get Leads action. Example: "abc123"

Output:

• FileId (string): The ID of the created file
• FileName (string): The name of the created file
• FileType (string): The type/extension of the created file
• FileSize (string): The size of the created file in bytes
• DealId (string): The ID of the associated deal
• DealTitle (string): The title of the associated deal
• PersonId (string): The ID of the associated person
• PersonName (string): The name of the associated person
• OrgId (string): The ID of the associated organization
• OrgName (string): The name of the associated organization
• ActivityId (string): The ID of the associated activity
• ProductId (string): The ID of the associated product
• ProductName (string): The name of the associated product
• ActivitySubject (string): The subject of the associated activity
• LeadId (string): The ID of the associated lead
• LeadTitle (string): The title of the associated lead
• CreatedTime (string): The timestamp when the file was created
• UpdateTime (string): The timestamp when the file was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by the Pipedrive API. Default 0 means the request never reached the server (network error). Use for debugging.
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Delete a File

WARNING: Permanently deletes a PipeDrive file record by file ID. This operation CANNOT BE UNDONE. Returns the file information before deletion for audit purposes. Deleting a file only removes the file record; associated Deal, Person, Organization, and Activity records remain intact. Returns file information retrieved BEFORE deletion for audit purposes (requires 2 API calls). Don't use when: archiving or closing a deal (use Update with Status field instead). Side effects: PERMANENTLY deletes the record; this action cannot be undone. Requires Confirm=true.

Input Parameters:

• FileId: Numeric file ID to delete (required). Obtain the FileId field from the response of 'Get a File' or 'Create a File' action. WARNING: Deletion is permanent and cannot be undone. Example: "301"

Options:

• Confirm: ⚠️ SAFETY GATE: Must be explicitly set to true to proceed with deletion. This operation is PERMANENT and CANNOT BE UNDONE. Prevents accidental deletion by Agent hallucinations or misunderstandings. Set to false to abort.

Output:

• FileId (string): The ID of the deleted file
• FileName (string): The name of the deleted file
• FileType (string): The type/extension of the deleted file
• FileSize (string): The size of the deleted file in bytes
• DealId (string): The ID of the associated deal
• DealTitle (string): The title of the associated deal
• PersonId (string): The ID of the associated person
• PersonName (string): The name of the associated person
• OrgId (string): The ID of the associated organization
• OrgName (string): The name of the associated organization
• ActivityId (string): The ID of the associated activity
• ActivitySubject (string): The subject of the associated activity
• CreatedTime (string): The timestamp when the file was created
• UpdateTime (string): The timestamp when the file was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error). Use for debugging.
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Download a File

Downloads the content of a PipeDrive file by file ID. Returns the file content as Base64 encoded string. Obtain FileId via Get a File or Search Files action. Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Input Parameters:

• FileId: Numeric file ID to download (required). Obtain via Get a File or Search Files action. Example: "301"

Output:

• FileId (string): The ID of the downloaded file
• FileName (string): The name of the downloaded file
• FileType (string): The type/extension of the downloaded file
• FileSize (string): The size of the downloaded file in bytes
• FileContent (string): The file content encoded as Base64 string (decode to save as file or pass to other systems)
• DealId (string): The ID of the associated deal
• DealTitle (string): The title of the associated deal
• PersonId (string): The ID of the associated person
• PersonName (string): The name of the associated person
• OrgId (string): The ID of the associated organization
• OrgName (string): The name of the associated organization
• ActivityId (string): The ID of the associated activity
• ActivitySubject (string): The subject of the associated activity
• CreatedTime (string): The timestamp when the file was created
• UpdateTime (string): The timestamp when the file was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from Pipedrive API (0 if network error before reaching server)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Get a File

Retrieves detailed information about a PipeDrive file by file ID. Returns file metadata and associated entity information. Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Input Parameters:

• FileId: File ID to retrieve details for (required). Obtain via Create a File action or file listing. Example: "301"

Output:

• FileId (string): The ID of the file
• FileName (string): The name of the file
• FileType (string): File extension (e.g., 'pdf', 'docx', 'png')
• FileSize (string): File size in bytes as a string. Example: "204800" represents 200KB
• DealId (string): The ID of the associated deal. Empty string if the file is not linked to any deal
• DealTitle (string): The title of the associated deal
• PersonId (string): The ID of the associated person. Empty string if the file is not linked to any person
• PersonName (string): The name of the associated person
• OrgId (string): The ID of the associated organization. Empty string if the file is not linked to any organization
• OrgName (string): The name of the associated organization
• ActivityId (string): The ID of the associated activity. Empty string if the file is not linked to any activity
• ActivitySubject (string): The subject of the associated activity
• CreatedTime (string): The timestamp when the file was created. Format: YYYY-MM-DD HH:MM:SS. Example: "2024-01-15 10:30:00"
• UpdateTime (string): The timestamp when the file was last updated. Format: YYYY-MM-DD HH:MM:SS. Example: "2024-01-16 14:20:00"
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Update Detail of a File

Updates the metadata and details of an existing PipeDrive file. This is a PATCH operation (partial update) — only the fields you provide will be modified; unfilled fields retain their original values. At least one of FileName or Description must be provided. ⚠️ Confirm must be set to true to execute the update. Don't use when: creating a new record → use the corresponding Create action. Side effects: modifies existing record using PATCH (incremental); only provided fields are changed, others retain their original values.

Input Parameters:

• FileId: File ID to update (required). Obtain via the 'Create a File' or 'Get Many Files' action. Example: "301"

Options:

• FileName: New file name to set (optional). At least one of FileName or Description must be provided. Include the file extension. Changing the name does not change the actual file content. Max length: 255 characters. Example: "contract_draft_v2.pdf"
• Description: New file description/notes (optional). Plain text only — HTML is not supported. Use to provide context about the file contents or version. Max length: 1000 characters. Example: "Revised contract draft for Q1 renewal, reviewed by legal team"
• Confirm: ⚠️ Safety gate: Must be explicitly set to true to execute the update. Prevents accidental modifications. When false, returns StatusCode=-1 with error message.

Output:

• FileId (string): The ID of the updated file
• FileName (string): The name of the updated file
• FileType (string): File extension without the leading dot (e.g. "pdf", "docx", "png"). Empty string if type is unknown.
• FileSize (string): File size in bytes as a numeric string (e.g. "204800" = 200 KB). Empty string if size is unknown.
• Description (string): The description of the updated file
• CreatedTime (string): The timestamp when the file was created. Format: YYYY-MM-DD HH:MM:SS
• UpdateTime (string): The timestamp when the file was last updated. Format: YYYY-MM-DD HH:MM:SS
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Create a Lead

⚠️ WARNING: This action does NOT check for duplicates — repeated calls with the same parameters will create multiple leads. Use Get Leads or Search Leads to verify before creating. Creates a new PipeDrive lead record. CONDITIONAL REQUIRED: At least one of PersonId or OrgId must be provided. Don't use when: modifying an existing record → use the corresponding Update action instead. Side effects: creates a permanent record; NOT idempotent — calling twice creates two records.

Input Parameters:

• Title: The title/name of the lead (required). A clear, descriptive title. Example: "Acme Corp - New Office Expansion"

Options:

• PersonId: ⚠️ CONDITIONAL REQUIRED: Either PersonId or OrgId must be provided (at least one is mandatory). Associated person ID (numeric). Business guidance: B2C scenario (individual customer) — fill PersonId only; B2B scenario (company deal) — fill OrgId, optionally add PersonId for the key contact. Obtain via Search Persons action (use the PersonId field from response) or Get Persons action. Example: 123
• OrgId: ⚠️ CONDITIONAL REQUIRED: Either PersonId or OrgId must be provided (at least one is mandatory). Associated organization ID (numeric). Business guidance: B2B scenario (company deal) — fill OrgId; B2C scenario (individual customer) — fill PersonId instead. Obtain via Search Organizations action (use the OrganizationId field from response) or Get Organizations action. Example: 456
• Value: Lead monetary value (optional, numeric). Must be >= 0. Leave empty if value is unknown. Example: 5000 or 1250.50
• Currency: Currency code (3 letters, ISO 4217). Default: USD. Required if Value is provided. Common values: USD, EUR, GBP, CNY, JPY, AUD, CAD. Example: "USD"
• AdditionalFields: Additional less common fields to set on the lead (optional). Supported keys: label_ids (array of label UUIDs), expected_close_date (string, YYYY-MM-DD), visible_to (number: 1=owner only, 3=entire company), was_seen (bool). Example: {"expected_close_date": "2024-06-30", "visible_to": 3}

Output:

• LeadId (string): UUID string of the created lead (e.g., "adf21080-0e10-11eb-879b-05d71fb426ec")
• Title (string): Title of the created lead
• Value (string): Monetary value of the lead as a numeric string without currency symbol. Format: plain number with optional decimal point, no thousand separators (e.g., "50000" for $50k, "1250.50" for $1,250.50). PipeDrive may return trailing zeros (e.g., "5000.0"). Empty string if not set.
• Currency (string): Three-letter currency code for the lead value (e.g., "USD", "EUR"). Empty string if value not set.
• PersonId (string): ID of the associated person as a string (e.g., "123"). Empty string if no person linked.
• PersonName (string): Full name of the associated person. Empty string if no person linked.
• OrgId (string): ID of the associated organization as a string (e.g., "456"). Empty string if no organization linked.
• OrgName (string): Name of the associated organization. Empty string if no organization linked.
• CreatedTime (string): Timestamp when the lead was created. Format: YYYY-MM-DD HH:MM:SS
• UpdateTime (string): Timestamp when the lead was last updated. Format: YYYY-MM-DD HH:MM:SS
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Delete a Lead

WARNING: Permanently deletes a PipeDrive lead record. This operation CANNOT BE UNDONE. The lead and all associated data will be irreversibly removed from the system. Use with caution. Don't use when: archiving or closing a deal (use Update with Status field instead). Side effects: PERMANENTLY deletes the record; this action cannot be undone. Requires Confirm=true.

Input Parameters:

• LeadId: Lead ID to delete (required). Obtain via Get Leads action. Pipedrive Lead IDs are UUID format. WARNING: Deletion is permanent and cannot be undone. Example: "aabbccdd-1234-5678-abcd-ef0123456789"

Options:

• Confirm: ⚠️ SAFETY GATE: Must be explicitly set to true to proceed with deletion. This operation is PERMANENT and CANNOT BE UNDONE. Prevents accidental deletion by Agent hallucinations or misunderstandings. Set to false to abort.

Output:

• LeadId (string): The ID of the deleted lead
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error). Use for debugging.
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Get Leads

Retrieves one or more PipeDrive lead records by ID (batch mode, max 50 IDs) or all leads via automatic pagination. Use 'Get Leads' when you already have specific Lead IDs (e.g., from 'Search Leads' action). Use 'Search Leads' to find leads by criteria (title, person, organization). Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Options:

• LeadIds: Comma-separated lead IDs to retrieve (optional, max 50 IDs). Lead IDs are UUID format (e.g., aabbccdd-1234-5678-abcd-ef0123456789). Both English comma (,) and Chinese comma (，) are supported. Obtain via the 'Search Leads' action. ⚠️ WARNING: If LeadIds is empty, this action retrieves ALL leads via automatic pagination — use with caution on accounts with large numbers of leads. Example: "aabbccdd-1234-5678-abcd-ef0123456789,bbccddee-2345-6789-bcde-f01234567890"

Output:

• Leads (object-array): Array of retrieved lead objects. Each object contains: LeadId (string: UUID format), Title (string), Value (string: monetary amount, plain number with optional decimal, e.g. "5000.0"), Currency (string: ISO code, e.g. USD), PersonId (string), PersonName (string), OrgId (string), OrgName (string), CreatedTime (string: YYYY-MM-DD HH:MM:SS), UpdateTime (string: YYYY-MM-DD HH:MM:SS)
• FailedItems (object-array): Array of failure objects (batch mode only, always empty [] in paginated mode). Each contains: LeadId (string: the UUID that failed), StatusCode (number: HTTP status code), ErrorMessage (string: error details)
• SuccessCount (number): Number of successfully retrieved leads
• TotalRequested (number): Total number of requested lead IDs (batch mode only, 0 in paginated mode)
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): First non-200 HTTP status code encountered from the Pipedrive API, or 200 if all succeeded. 0 if request never reached the server (e.g. parameter validation failed).
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Empty string on full success; describes failure summary on partial/full failure

Update a Lead

⚠️ Incremental Update: Updates an existing PipeDrive lead record using PATCH method. Only the provided fields will be updated — fields left empty retain their original values. This allows safe partial updates without affecting other lead details. Don't use when: creating a new record → use the corresponding Create action. Side effects: modifies existing record using PATCH (incremental); only provided fields are changed, others retain their original values.

Input Parameters:

• LeadId: The ID of the lead to update (required). Obtain via Get Leads action. Lead IDs are UUIDs. Example: "aabbccdd-1234-5678-abcd-ef0123456789"

Options:

• Title: New lead title (optional). Example: "Inbound Lead - Q1 2024 Updated"
• PersonId: Associated contact person ID (optional). Obtain via Search Persons action. Example: "123"
• OrgId: Associated organization ID (optional). Obtain via Search Organizations action. Example: "456"
• Value: Lead value amount (optional). Numeric value, supports decimals. Update behavior: if left empty, the original value is preserved; set to 0 to clear the value. If Currency is not specified alongside, defaults to USD. Example: 7500
• Currency: Currency for the lead value (optional). Use the 3-letter international standard currency code (ISO 4217, e.g. USD, EUR, GBP). Update behavior: only effective when Value is also provided; cannot update currency alone without updating value. Common codes: USD (US Dollar), EUR (Euro), GBP (British Pound), CNY (Chinese Yuan). Example: "USD"
• OwnerId: Lead owner user ID (optional). Assign the lead to a specific user. Obtain via Get Users action. Example: 789
• ExpectedCloseDate: Expected close date (optional). Format: YYYY-MM-DD. Example: "2024-12-31"
• AdditionalFields: Additional lead fields as a JSON object (optional). Supports less common Pipedrive lead fields not covered by named parameters. Common fields: label_ids (array: lead label IDs, obtain via Get Lead Labels), visible_to (number: 1=owner only, 3=entire company), is_archived (bool: true to archive). Example: {"label_ids": [1, 2], "visible_to": 3, "is_archived": false}

Common fields:

• label_ids (array): Lead label IDs, obtain via Get Lead Labels
• visible_to (number): 1=owner only, 3=entire company, 7=owner and followers
• is_archived (bool): true to archive the lead
• was_seen (bool): mark as seen/unseen
• source_name (string): lead source name

Output:

• LeadId (string): The ID of the updated lead
• Title (string): The title of the updated lead
• Value (string): The value amount of the updated lead. Returned as string (e.g. "7500.0") to preserve decimal precision; convert to number if arithmetic operations are needed.
• Currency (string): The currency code of the lead value
• PersonId (string): The ID of the associated person
• PersonName (string): The name of the associated person
• OrgId (string): The ID of the associated organization
• OrgName (string): The name of the associated organization
• CreatedTime (string): The timestamp when the lead was created. Format: YYYY-MM-DD HH:MM:SS
• UpdateTime (string): The timestamp when the lead was last updated. Format: YYYY-MM-DD HH:MM:SS
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Create a Note

Creates a new PipeDrive note record with the specified content. The note can be associated with deals, contacts, organizations, leads, or projects simultaneously. At least one association is recommended for better tracking. Don't use when: modifying an existing record → use the corresponding Update action instead. Side effects: creates a permanent record; NOT idempotent — calling twice creates two records. Recovery: if created by mistake, use the Delete a Note action to remove it.

Input Parameters:

• Content: Note content (required). Supports plain text and basic HTML tags such as <b>, <i>, <a>, <br>, <p>, <ul>, and <li>. Max 65535 characters. For plain text line breaks use \n. Example: "Meeting notes: Discussed Q1 targets and <b>agreed on follow-up actions</b>."

Options:

• DealId: Associated deal ID (optional). Obtain via Search Deals or Get Deals action. Example: "789"
• PersonId: Associated person ID (optional). Obtain via Search Persons or Get Persons action. Example: "123"
• OrgId: Associated organization ID (optional). Obtain via Search Organizations or Get Organizations action. Example: "456"
• LeadId: Associated lead ID (optional, UUID string format). Obtain via Search Leads or Get Leads action. Example: "abc123-def456-789ghi"
• ProjectId: Associated project ID (optional). Obtain via Get Projects action. Example: "10"
• Confirm: Safety gate: must be set to true to create the note. Prevents accidental duplicate creation since this action is NOT idempotent. Example: true

Output:

• NoteId (string): The ID of the created note
• Content (string): The content of the created note
• DealId (string): The ID of the associated deal. Empty string if no deal is associated with this note.
• DealTitle (string): The title of the associated deal. Empty string if no deal is associated with this note.
• PersonId (string): The ID of the associated person. Empty string if no person is associated with this note.
• PersonName (string): The name of the associated person. Empty string if no person is associated with this note.
• OrgId (string): The ID of the associated organization. Empty string if no organization is associated with this note.
• OrgName (string): The name of the associated organization. Empty string if no organization is associated with this note.
• LeadId (string): The ID of the associated lead (UUID format). Empty string if no lead is associated with this note.
• LeadTitle (string): The title of the associated lead. Empty string if no lead is associated with this note.
• ProjectId (string): The ID of the associated project. Empty string if no project is associated with this note.
• ProjectTitle (string): The title of the associated project. Empty string if no project is associated with this note.
• CreatedTime (string): The timestamp when the note was created
• UpdateTime (string): The timestamp when the note was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by the Pipedrive API (0 if request never reached the server due to network error). Use for debugging.
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Delete a Note

WARNING: Permanently deletes a PipeDrive note record. This operation CANNOT BE UNDONE. Use with caution. Don't use when: archiving or closing a deal (use Update with Status field instead). Side effects: PERMANENTLY deletes the record; this action cannot be undone. Requires Confirm=true.

Input Parameters:

• NoteId: Numeric note ID to delete (required). Obtain via Get Notes action. WARNING: Deletion is permanent and cannot be undone. Example: "201"

Options:

• Confirm: ⚠️ SAFETY GATE: Must be explicitly set to true to proceed with deletion. This operation is PERMANENT and CANNOT BE UNDONE. Prevents accidental deletion by Agent hallucinations or misunderstandings. Set to false to abort.

Output:

• NoteId (string): The ID of the deleted note
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error). Use for debugging.
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Get Notes

Retrieves one or more PipeDrive note records by ID (batch mode, max 50 IDs) or all notes via automatic pagination. Use 'Get Notes' when you already have specific Note IDs (e.g., from 'Search Notes' action). ⚠️ Paginated mode (NoteIds empty): retrieves ALL notes in your account — may be slow for accounts with 10,000+ notes. Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Options:

• NoteIds: Comma-separated note IDs to retrieve (optional, max 50 IDs). Numeric IDs only (e.g., "201,202,203"). Both English comma (,) and Chinese comma (，) are supported. Obtain IDs via the 'Search Notes' action. If empty, retrieves all notes with automatic pagination. ⚠️ Warning: For accounts with 10,000+ notes, paginated mode may take several minutes. Example: "201,202,203"

Output:

• Notes (object-array): Array of retrieved note objects. Each object contains: NoteId (string), Content (string), DealId (string), DealTitle (string), PersonId (string), PersonName (string), OrgId (string), OrgName (string), LeadId (string), LeadTitle (string), CreatedTime (string: YYYY-MM-DD HH:MM:SS), UpdateTime (string: YYYY-MM-DD HH:MM:SS)
• FailedItems (object-array): Array of failure objects (batch mode only, always empty [] in paginated mode). Each contains: NoteId (string: the ID that failed), StatusCode (number: HTTP status code), ErrorMessage (string: error details)
• SuccessCount (number): Number of successfully retrieved notes
• TotalRequested (number): Total number of requested note IDs (batch mode only, 0 in paginated mode)
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): First non-200 HTTP status code encountered from the Pipedrive API, or 200 if all succeeded. 0 if request never reached the server (e.g. parameter validation failed).
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Update a Note

Updates an existing PipeDrive note record with new information. Only the provided fields will be updated, allowing partial updates of note details. ⚠️ At least one field (Content, DealId, PersonId, OrgId, or LeadId) must be provided for update — calling with only NoteId and no other fields will return an error. Don't use when: creating a new record → use the corresponding Create action. Side effects: modifies existing record using PATCH (incremental); only provided fields are changed, others retain their original values.

Input Parameters:

• NoteId: The ID of the note to update (required). Obtain via Get Notes action. Example: "12345"

Options:

• Content: New note content (optional). Supports plain text and basic HTML formatting such as <b>, <i>, <ul>, <li>, and <a>. ⚠️ At least one update field must be provided — see Action Note. Example: "Follow-up meeting scheduled for next Monday at 10 AM."
• DealId: Associate note with a deal (optional). Obtain via Search Deals or Get Deals action. Example: "67890". Must be a numeric string.
• PersonId: Associate note with a person (optional). Obtain via Search Persons action. Example: "54321". Must be a numeric string.
• OrgId: Associate note with an organization (optional). Obtain via Search Organizations action. Example: "98765". Must be a numeric string.
• LeadId: Associate note with a lead (optional). Obtain via Get Leads action. Lead IDs are UUIDs. Example: "aabbccdd-1234-5678-abcd-ef0123456789"

Output:

• NoteId (string): The ID of the updated note
• Content (string): The content of the updated note
• DealId (string): The ID of the associated deal. Empty string if no deal is associated with this note.
• DealTitle (string): The title of the associated deal. Empty string if no deal is associated with this note.
• PersonId (string): The ID of the associated person. Empty string if no person is associated with this note.
• PersonName (string): The name of the associated person. Empty string if no person is associated with this note.
• OrgId (string): The ID of the associated organization. Empty string if no organization is associated with this note.
• OrgName (string): The name of the associated organization. Empty string if no organization is associated with this note.
• LeadId (string): The ID of the associated lead (UUID format). Empty string if no lead is associated with this note.
• LeadTitle (string): The title of the associated lead. Empty string if no lead is associated with this note.
• CreatedTime (string): The timestamp when the note was created
• UpdateTime (string): The timestamp when the note was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Create an Organization

Creates a new PipeDrive organization record with the specified name and optional contact details. WARNING: This action does not prevent duplicate creation (non-idempotent) — if the request times out and is retried, multiple organizations with the same name may be created. Best practice: Search for an existing organization before creating a new one. 💡 TIP: To prevent duplicates, use the Search Organizations action (ToolName: pipedrive_search_organizations) first to check if the organization already exists. Don't use when: modifying an existing record → use the corresponding Update action instead. Side effects: creates a permanent record; calling twice creates two records.

Input Parameters:

• Confirm: ⚠️ Confirmation required: Must be explicitly set to true to create the organization. Prevents accidental duplicate creation during Agent retries. If false or omitted, returns StatusCode=-1.
• Name: Organization name (required). Use the company's full official name. Example: "Acme Corporation"

Options:

• Address: Organization's physical address (optional). Example: "123 Main St, San Francisco, CA 94105"
• Phone: Organization's phone number (optional). Supports international format. Example: "+1-555-0200"
• Email: Organization's email address (optional). Example: "contact@acme.com"
• Website: Organization's website URL (optional). Include the protocol prefix. Example: "https://www.acme.com"
• OwnerId: Pipedrive user ID of the organization owner (optional). DEFAULT: If omitted, the organization will be owned by the API token owner. To assign to a different user, obtain the user ID via Get Many Users action (ToolName: pipedrive_get_users). Must be a numeric string. Example: "12345"

Output:

• OrganizationId (string): The ID of the created organization
• Name (string): The name of the created organization
• Address (string): The address of the created organization
• Phone (string): The phone number of the created organization
• Email (string): The email address of the created organization
• Website (string): The website URL of the created organization
• OwnerId (string): The ID of the organization owner
• OwnerName (string): The name of the organization owner
• PeopleCount (number): Number of people associated with this organization (integer)
• DealsCount (number): Number of deals associated with this organization (integer)
• ActivitiesCount (number): Number of activities associated with this organization (integer)
• CreatedTime (string): Timestamp when the organization was created (UTC). Format: YYYY-MM-DD HH:MM:SS. Example: "2024-01-15 10:30:00"
• UpdateTime (string): Timestamp when the organization was last updated (UTC). Format: YYYY-MM-DD HH:MM:SS. Example: "2024-01-15 10:30:00"
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Delete an Organization

WARNING: Permanently deletes a PipeDrive organization record and returns organization details before deletion. This operation CANNOT BE UNDONE. Use with caution. Deleting an organization only removes the organization record; associated Deal, Person, and Activity records remain intact. Returns organization information retrieved BEFORE deletion for audit purposes (requires 2 API calls). Don't use when: archiving or closing a deal (use Update with Status field instead). Side effects: PERMANENTLY deletes the record; this action cannot be undone. Requires Confirm=true.

Input Parameters:

• OrganizationId: Numeric organization ID to delete (required). Obtain via Search Organizations or Get Organizations action. WARNING: Deletion is permanent and cannot be undone. Example: "456"

Options:

• Confirm: ⚠️ SAFETY GATE: Must be explicitly set to true to proceed with deletion. This operation is PERMANENT and CANNOT BE UNDONE. Prevents accidental deletion by Agent hallucinations or misunderstandings. Set to false to abort.

Output:

• OrganizationId (string): The ID of the deleted organization
• Name (string): The name of the deleted organization
• Address (string): The address of the deleted organization
• Phone (string): The phone number of the deleted organization
• Email (string): The email address of the deleted organization
• Website (string): The website URL of the deleted organization
• OwnerId (string): The ID of the organization owner
• OwnerName (string): The name of the organization owner
• PeopleCount (string): The number of people associated with the organization
• DealsCount (string): The number of deals associated with the organization
• ActivitiesCount (string): The number of activities associated with the organization
• CreatedTime (string): The timestamp when the organization was created
• UpdateTime (string): The timestamp when the organization was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error). Use for debugging.
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Get Organizations

Retrieves multiple PipeDrive organization records by IDs. Supports batch operations with detailed success and failure reporting. Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Input Parameters:

• OrganizationIds: Comma-separated list of organization IDs to retrieve (required, max 50 IDs). Obtain the OrganizationId field from Search Organizations action results. Both English comma (,) and Chinese comma (，) are supported. Spaces around commas are trimmed automatically. Example: "456,457,458"

Output:

• Organizations (object-array): Array of organization objects. Each object contains: OrganizationId (string), Name (string), Address (string: empty if not set), Phone (string: empty if not set), Email (string: empty if not set), Website (string: empty if not set), OwnerId (string: empty if not set), OwnerName (string), PeopleCount (string: number of associated persons), DealsCount (string: number of associated deals), ActivitiesCount (string: number of associated activities), CreatedTime (string: YYYY-MM-DD HH:MM:SS), UpdateTime (string: YYYY-MM-DD HH:MM:SS)
• SuccessCount (number): Number of organizations successfully retrieved (integer)
• FailedItems (object-array): Array of failure objects for IDs that could not be retrieved. Each object contains: OrganizationId (string: the ID that failed), StatusCode (number: HTTP status code, e.g. 404=not found, 401=unauthorized), ErrorMessage (string: reason for failure)
• TotalRequested (number): Total number of organization IDs requested (integer)
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): First non-200 HTTP status code encountered during batch retrieval, or 200 if all succeeded. 0 if request never reached the server (e.g. parameter validation failed). For debugging; regular users can ignore this field.
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Search Organizations

Searches PipeDrive organization records by keyword. Supports fuzzy/partial matching across name, address, and notes. Use NextCursor to paginate through results — pass it as Cursor in the next call. Returns up to 500 results per page. Don't use when: you already have a specific ID → use the corresponding Get action directly for better performance. Side effects: read-only, no data is modified.

Input Parameters:

• Term: Search keyword for finding organizations (required, minimum 2 characters). Supports fuzzy/partial matching. Searches across organization name, address, and notes. Use the OrganizationId from results with Update Organization, Delete Organization, or Get Organizations actions. Example: "Acme Corporation"

Options:

• Limit: Maximum number of results to return per page (optional, default 10, max 500). Example: 20
• Cursor: Pagination cursor for fetching the next page of results. Leave empty for the first page. Copy the NextCursor value from the previous response to get the next page. Example: "eyJpZCI6MTIzfQ"

Output:

• Organizations (object-array): Array of matching organization objects. Each object contains: OrganizationId (string), Name (string), Address (string), Phone (string), Email (string), OwnerId (string), OwnerName (string), PeopleCount (string: number as string, e.g. "5"), DealsCount (string: number as string), ActivitiesCount (string: number as string), CreatedTime (string: YYYY-MM-DD HH:MM:SS), UpdateTime (string: YYYY-MM-DD HH:MM:SS).
• CurrentCount (number): Number of organizations returned in the current page
• NextCursor (string): Cursor for next page (empty string if no more results). Pass this value as Cursor in the next call to retrieve the following page.
• SearchTerm (string): The search term used
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Update an Organization

Updates a PipeDrive organization record with new details. Allows partial updates of organization fields. Don't use when: creating a new record → use the corresponding Create action. Side effects: modifies existing record using PATCH (incremental); only provided fields are changed, others retain their original values.

Input Parameters:

• OrganizationId: The ID of the organization to update (required). Obtain via Search Organizations action. Example: "12345"

Options:

• Name: New organization name (optional). Example: "Acme Corporation"
• Address: New organization address (optional). Example: "123 Business Street, San Francisco, CA 94105"
• Phone: New phone number (optional). Example: "+1-415-555-0123"
• Email: New email address (optional). Format: user@example.com. Example: "contact@acme.com"
• Website: New website URL (optional). Must include protocol. Example: "https://www.acme.com"
• OwnerId: Owner (user) ID — the sales rep responsible for this organization (optional). Must be a numeric ID. Obtain via Get Users action. Example: "67890"

Output:

• OrganizationId (string): The ID of the updated organization
• Name (string): The name of the updated organization
• Address (string): The address of the updated organization
• Phone (string): The phone number of the updated organization
• Email (string): The email address of the updated organization
• Website (string): The website URL of the updated organization
• OwnerId (string): The ID of the organization owner
• OwnerName (string): The name of the organization owner
• PeopleCount (string): The number of people associated with the organization (numeric string, e.g. "5"; use int() to convert for arithmetic)
• DealsCount (string): The number of deals associated with the organization (numeric string, e.g. "5"; use int() to convert for arithmetic)
• ActivitiesCount (string): The number of activities associated with the organization (numeric string, e.g. "5"; use int() to convert for arithmetic)
• CreatedTime (string): The timestamp when the organization was created
• UpdateTime (string): The timestamp when the organization was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Create a Person

Creates a new PipeDrive person (contact) record. NOTE: This action does not check for duplicates — use Search Persons first if deduplication is needed. Don't use when: modifying an existing record → use the corresponding Update action instead. Side effects: creates a permanent record; NOT idempotent — calling twice creates two records.

Input Parameters:

• Name: Person full name (required). This is the primary display name in PipeDrive. If FirstName and LastName are also provided, they serve as structured fields. Example: "John Smith"

Options:

• FirstName: Person first name (optional). Stored separately for structured contact management. Example: "John"
• LastName: Person last name (optional). Stored separately for structured contact management. Example: "Smith"
• Phone: Phone number (optional). Supports international format. Note: PipeDrive internally stores phone as an array; this action accepts a single phone string and handles the conversion automatically. Example: "+1-555-0100" or "138-0000-0000"
• Email: Email address (optional). Used for contact and deduplication. Note: PipeDrive internally stores email as an array; this action accepts a single email string and handles the conversion automatically. Example: "john.smith@acme.com"
• OrganizationId: The numeric ID of the organization (company) to associate this person with (optional). If left empty, the Person will not be linked to any organization. Obtain via Search Organizations or Get Organizations action. Example: "456"

Output:

• PersonId (string): The ID of the created person
• Name (string): The full name of the created person
• FirstName (string): The first name of the created person
• LastName (string): The last name of the created person
• Phone (string): The phone number of the created person
• Email (string): The email address of the created person
• OrganizationId (string): The ID of the associated organization
• OrganizationName (string): The name of the associated organization
• OwnerId (string): The ID of the person owner
• OwnerName (string): The name of the person owner
• CreatedTime (string): The timestamp when the person was created
• UpdateTime (string): The timestamp when the person was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never reached server; 200/201=success; 400=bad request; 401=unauthorized; 429=rate limit)
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Delete a Person

WARNING: Permanently deletes a PipeDrive person record and returns person details before deletion. This operation CANNOT BE UNDONE. Use with caution. Deleting a person only removes the person record; associated Deal, Organization, and Activity records remain intact. Returns person information retrieved BEFORE deletion for audit purposes (requires 2 API calls). Don't use when: archiving or closing a deal (use Update with Status field instead). Side effects: PERMANENTLY deletes the record; this action cannot be undone. Requires Confirm=true.

Input Parameters:

• PersonId: Numeric person ID to delete (required). Obtain via Search Persons or Get Persons action. WARNING: Deletion is permanent and cannot be undone. Example: "123"

Options:

• Confirm: ⚠️ SAFETY GATE: Must be explicitly set to true to proceed with deletion. This operation is PERMANENT and CANNOT BE UNDONE. Prevents accidental deletion by Agent hallucinations or misunderstandings. Set to false to abort.

Output:

• PersonId (string): The ID of the deleted person
• Name (string): The full name of the deleted person
• FirstName (string): The first name of the deleted person
• LastName (string): The last name of the deleted person
• Phone (string): The phone number of the deleted person
• Email (string): The email address of the deleted person
• OrganizationId (string): The ID of the associated organization
• OrganizationName (string): The name of the associated organization
• OwnerId (string): The ID of the person owner
• OwnerName (string): The name of the person owner
• CreatedTime (string): The timestamp when the person was created
• UpdateTime (string): The timestamp when the person was last updated
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code from the Pipedrive API (0 if request never reached the server due to network error). Use for debugging.
• StatusCode (number): Operation result code: 200=success or business error (check ErrorMessage), -1=parameter validation error, 500=network error (Agent may retry)
• ErrorMessage (string): Error message description, empty string if successful

Get Persons

Retrieves multiple PipeDrive person records by IDs. Supports batch operations with detailed success and failure reporting. Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Input Parameters:

• PersonIds: Comma-separated list of person IDs to retrieve (required, max 50 IDs). Obtain via Search Persons action (extract from PersonId field in search results). Both English comma (,) and Chinese comma (，) are supported. Example: "123,124,125"

Output:

• Persons (object-array): Array of person objects. Each object contains:
• PersonId (string): Person unique ID
• Name (string): Full name
• FirstName (string): First name
• LastName (string): Last name
• Email (string): Primary email address
• Phone (string): Primary phone number
• Organization (string): Associated organization name
• OrganizationId (string): Associated organization ID, empty if not linked
• OwnerId (string): Owner user ID
• OwnerName (string): Owner name
• DealsCount (string): Number of closed deals (returned as string by PipeDrive API; convert to number if arithmetic needed)
• ActivitiesCount (string): Number of activities (returned as string by PipeDrive API; convert to number if arithmetic needed)
• CreatedTime (string): Creation time in YYYY-MM-DD HH:MM:SS format
• UpdateTime (string): Last update time in YYYY-MM-DD HH:MM:SS format
• SuccessCount (number): Number of persons successfully retrieved
• FailedItems (object-array): Array of failure objects for person IDs that could not be retrieved. Each object contains:
• PersonId (string): The person ID that failed
• StatusCode (number): HTTP status code. Common values: 401=unauthorized, 403=forbidden, 404=person not found, 429=rate limited, 500=server error
• ErrorMessage (string): Detailed reason for failure
• TotalRequested (number): Total number of person IDs requested
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): First non-200 HTTP status code encountered during batch retrieval, or 200 if all succeeded. 0 if request never reached the server (e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Search Persons

Searches for PipeDrive person records using cursor-based pagination. Returns next_cursor from API response for seamless pagination navigation. Don't use when: you already have a specific ID → use the corresponding Get action directly for better performance. Side effects: read-only, no data is modified.

Input Parameters:

• Term: Search keyword for finding persons (required, minimum 2 characters). Supports fuzzy matching of name, email, or phone. Example: "John Smith" or "john@example.com"

Options:

• Limit: Maximum number of results to return per page (optional, default 10, max 500 enforced by PipeDrive API; requesting more than 500 returns only 500). Example: 20
• Cursor: Pagination cursor to fetch the next page of results (leave empty for the first page). Obtain from the NextCursor field in the previous response. Example: "eyJhbGciOiJIUzI1NiJ9"

Output:

• Persons (object-array): Array of matching person objects. Each object contains: PersonId (string): unique person ID; Name (string): full name; FirstName (string): first name; LastName (string): last name; Email (string): email address; Phone (string): phone number; Organization (string): associated organization name; OrganizationId (string): associated organization ID, empty if not linked; OwnerId (string): owner user ID; OwnerName (string): owner user name; DealsCount (string): number of associated deals; ActivitiesCount (string): number of associated activities; CreatedTime (string: YYYY-MM-DD HH:MM:SS): creation timestamp; UpdateTime (string: YYYY-MM-DD HH:MM:SS): last update timestamp.
• NextCursor (string): Cursor for next page (empty if no more results)
• CurrentCount (number): Number of results in current page
• SearchTerm (string): The search term used
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Update a Person

Updates a PipeDrive person record with new details. Update Strategy: PATCH (Partial Update) — only the fields you provide will be updated; fields left empty will retain their original values. This is NOT a full replacement (PUT). ⚠️ At least one optional field (Name, FirstName, LastName, Email, Phone, OrganizationId, or OwnerId) must be provided for update. Don't use when: creating a new record → use the corresponding Create action. Side effects: modifies existing record using PATCH (incremental); only provided fields are changed, others retain their original values.

Input Parameters:

• PersonId: The ID of the person to update (required). Obtain via Search Persons or Get Persons action. Example: "12345"

Options:

• Name: Full name of the person (optional). Example: "John Doe"
• FirstName: First name of the person (optional). Example: "John"
• LastName: Last name of the person (optional). Example: "Doe"
• Email: Email address of the person (optional). Example: "john.doe@example.com"
• Phone: Phone number of the person (optional). Example: "+1-555-0100"
• OrganizationId: Organization ID to associate with this person (optional). Must be a numeric ID. Obtain via Search Organizations action. Example: "67890"
• OwnerId: Owner (user) ID to assign this person to (optional). Must be a numeric ID. Obtain via Get Users action. Example: "101"

Output:

• PersonId (string): The ID of the updated person
• Name (string): The name of the updated person
• FirstName (string): The first name of the updated person
• LastName (string): The last name of the updated person
• Email (string): The email address of the updated person
• Phone (string): The phone number of the updated person
• Organization (string): The organization name of the updated person
• OrganizationId (string): The organization ID of the updated person
• OwnerId (string): The ID of the person owner
• OwnerName (string): The name of the person owner
• DealsCount (number): The number of deals associated with the person
• ActivitiesCount (number): The number of activities associated with the person
• CreatedTime (string): The timestamp when the person was created. Format: YYYY-MM-DD HH:MM:SS
• UpdateTime (string): The timestamp when the person was last updated. Format: YYYY-MM-DD HH:MM:SS
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): HTTP status code returned by PipeDrive API (0 if request never sent, e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

Get Products

Retrieves PipeDrive products using API v2. Supports both batch retrieval by IDs and cursor-based paginated listing of all products. Returns arrays of JSON strings for Products and FailedItems. Don't use when: searching by name or keyword → use the corresponding Search action instead. Requires a known ID. Side effects: read-only, no data is modified.

Options:

• ProductIds: Comma-separated product IDs for batch retrieval (optional, max 50 IDs). Obtain IDs via Search Products action. Both English comma (,) and Chinese comma (，) are supported. Example: "501,502,503". If empty, uses paginated listing mode.
• Limit: Maximum number of products to return per page for paginated listing (optional, default: 100, max: 500). Example: 50
• Cursor: Page marker for retrieving the next page (leave empty for the first page). Use the NextCursor value from the previous response.

Output:

• Products (object-array): Array of product objects (each element is one product). Each object contains: ProductId (string), Name (string: product name), Code (string: SKU/code, may be empty), Description (string), Unit (string), Tax (string: tax percentage), Category (string), ActiveFlag (string: "True" or "False"), OwnerId (string: empty if no owner), OwnerName (string), SellerName (string), FirstChar (string), VisibleTo (string), CreatedTime (string: YYYY-MM-DD HH:MM:SS), UpdateTime (string: YYYY-MM-DD HH:MM:SS). If price data exists: Price (string: numeric amount), Currency (string: ISO 4217 code), Cost (string), OverheadCost (string)
• SuccessCount (number): Number of products successfully retrieved (integer)
• FailedItems (object-array): Array of failure objects (batch mode only; always empty array [] in paginated mode). Each object contains: ProductId (string: the ID that failed), StatusCode (number: HTTP status code, e.g. 404=not found, 401=unauthorized), ErrorMessage (string: reason for failure)
• TotalRequested (number): Total number of product IDs requested in batch mode (integer, 0 in paginated mode)
• TotalCount (number): Total number of products in the catalog (integer, paginated mode only, 0 in batch mode)
• NextCursor (string): Cursor value for the next page (empty if no next page)
• HasNextPage (bool): Whether there are more results available
• Summary (string): A brief summary of the operation result (e.g. how many records were found or retrieved). Empty string if not applicable.
• Hint (string): Actionable guidance for Agent on the next step when an error occurs. Empty string on success.
• Retryable (bool): Whether the operation can be retried. true for transient errors (network timeout, rate limit), false for permanent errors (invalid params, not found, auth).
• OriginalStatusCode (number): First non-200 HTTP status code encountered, or 200 if all succeeded. 0 if request never reached the server (e.g. parameter validation failed)
• StatusCode (number): Tool-level status code. 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Error message description, empty string if successful

5. Example Usage

This section demonstrates how to build a simple workflow to create a new deal in your Pipedrive account.

The workflow will consist of three nodes: Start -> Create a Deal -> Answer.

1. Add the Pipedrive Node

• In the workflow canvas, click the + button to add a new node.
• Select the Tools tab in the pop-up panel.
• Find and select Pipedrive from the list of tools.
• From the list of supported operations for Pipedrive, click on Create a Deal. This will add the node to your canvas.

2. Configure the Node

• Click on the newly added Create a Deal node to open its configuration panel on the right.
• Credentials: In the Credentials field at the top of the panel, click the dropdown menu and select your pre-configured Pipedrive credential.
• Parameters: Fill in the required input parameters for the action.
  • Title: Enter a descriptive title for the new deal, for example, New Q4 Project for Globex Corp.
  • Value: (Optional) Enter the monetary value of the deal, such as 25000.
  • Currency: (Optional) Specify the currency code, for example, USD.
  • PersonId: (Optional) If you want to link this deal to an existing contact, provide their Person ID here. You can get this ID from a previous Search Persons node.
  • OrgId: (Optional) Similarly, provide an Organization ID to link the deal to an existing organization.

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
• Click the Run button in the top-right corner of the canvas to execute the workflow.
• After a successful execution, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the deal was created and retrieving its new DealId.

After completing these steps, your workflow is fully configured. When executed, it will create a new deal in your Pipedrive account with the details you provided.

6. FAQs

Q: Why am I getting a 401 Unauthorized or 403 Forbidden error?

A: This typically indicates an issue with your API credentials. Please check the following:

• Correct API Token: Ensure the API token you entered in the GoInsight credential configuration is correct and has not expired.
• Permissions: Verify that the user associated with the API token has the necessary permissions in Pipedrive to perform the requested action (e.g., create deals, read contacts).

Q: How do I find the PersonId or OrgId to associate with a new deal or activity?

A: You can build a multi-step workflow. In a step before creating the deal, use the Search Persons or Search Organizations operation with a known term (like an email address or company name). The output of that search node will provide the PersonId or OrgId, which you can then reference in the input fields of the Create a Deal node.

Q: My Create a File action is failing. What's a common issue?

A: The most common issues with file creation are:

• Invalid Base64: The content provided in the FileContent field must be a valid Base64 encoded string. Make sure your source data is correctly encoded before passing it to the node.
• Missing Association: Pipedrive requires a file to be associated with at least one other entity. You must provide a valid ID for at least one of the optional parameters like DealId, PersonId, or OrgId.

7. Official Documentation

For more detailed information about the Pipedrive API, including all available endpoints and parameters, please refer to the Pipedrive Official API Documentation.