# Pipedrive

> Sales CRM platform for managing persons, deals, notes, activities, and pipelines with comprehensive API access.

Source: https://cotera.co/docs/reference/tools/individual-tools/pipedrive

---

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

***

## Authentication

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

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

For more details, see the [Pipedrive API documentation](https://developers.pipedrive.com/docs/api/v1).

***

## Persons

Manage contacts and individuals in your Pipedrive CRM.

### Search Persons

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

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

### Get Person

Retrieve a specific person by their ID.

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

```json
{
  "personId": 12345
}
```

### List Persons

Retrieve a paginated list of all persons.

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

### Add Person

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

**Operation Type:** Mutation (Write)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

### Update Person

Update an existing person's information.

**Operation Type:** Mutation (Write)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

### Get Person Activities

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

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

***

## Deals

Manage sales deals and opportunities in your Pipedrive CRM pipeline.

### Search Deals

Search for deals by title or notes.

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

### Get Deal

Retrieve a specific deal by its ID.

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

```json
{
  "dealId": 54321
}
```

### List Deals

Retrieve a paginated list of all deals.

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

### Create Deal

Create a new deal in your sales pipeline.

**Operation Type:** Mutation (Write)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

### Update Deal

Update an existing deal's properties.

**Operation Type:** Mutation (Write)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

***

## Notes

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

### Create Note

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

**Operation Type:** Mutation (Write)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

### List Notes

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

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

### Get Note

Retrieve a specific note by its ID.

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

```json
{
  "noteId": 98765
}
```

### Update Note

Update an existing note's content or pin status.

**Operation Type:** Mutation (Write)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

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

***

## Pipelines

View sales pipeline configurations for organizing deal progression.

### List Pipelines

Retrieve all pipelines in your Pipedrive account.

**Operation Type:** Query (Read)

**Parameters:**

* None

**Returns:**

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

**Example Usage:**

```json
{}
```

***

## Stages

View pipeline stages for tracking deal progression.

### List Stages

Retrieve all stages, optionally filtered by pipeline.

**Operation Type:** Query (Read)

**Parameters:**

* **pipelineId** `number` (nullable): Filter by pipeline ID

**Returns:**

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

**Example Usage:**

```json
{
  "pipelineId": 1
}
```

***

## Mail Messages

Access email messages linked to your Pipedrive CRM records.

### Get Mail Message

Retrieve a specific mail message by its ID.

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

```json
{
  "mailMessageId": 11111
}
```

***

## Organizations

Access organization (company) records in Pipedrive.

### Get Organization

Retrieve a specific organization by its ID.

**Operation Type:** Query (Read)

**Parameters:**

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

**Returns:**

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

**Example Usage:**

```json
{
  "orgId": 99999
}
```

***

## Common Use Cases

**Deal Management:**

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

**Contact Intelligence:**

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

**Activity Tracking:**

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

**Pipeline Analytics:**

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