> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipedrive: Get Persons

> List Pipedrive people, filtered by owner, organization, deal or update date. Includes SDK V2 examples, input constraints, response fields, and Deepline cost.

List Pipedrive people, filtered by owner, organization, deal or update date.

> [!NOTE]
>
> Tool ID: `pipedrive_get_persons`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'pipedrive_get_persons',
  {
    "filter_id": 123,
    "ids": "example",
    "owner_id": 123
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute pipedrive_get_persons --input '{
  "filter_id": 123,
  "ids": "example",
  "owner_id": 123
}' --json
```

## Example response

The SDK returns this shape at `result.toolResponse.raw`. The example values illustrate the response.

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "data": {
    "success": true,
    "data": [
      {
        "id": 123,
        "name": "Example",
        "first_name": "Jane"
      }
    ],
    "additional_data": {
      "next_cursor": "cursor_123"
    }
  }
}
```

Use `deepline describe pipedrive_get_persons --json` for the latest machine-readable contract.

## Input reference

Returns data about all persons. Fields `ims`, `postal_address`, `notes`, `birthday`, and `job_title` are only included if contact sync is enabled for the company.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.filter_id` | `integer` | No | — | If supplied, only persons matching the specified filter are returned |
| `payload.ids` | `string` | No | — | Optional comma separated string array of up to 100 entity ids to fetch. If filter\_id is provided, this is ignored. If any of the requested entities do not exist or are not visible, they are not included in the response. |
| `payload.owner_id` | `integer` | No | — | If supplied, only persons owned by the specified user are returned. If filter\_id is provided, this is ignored. |
| `payload.org_id` | `integer` | No | — | If supplied, only persons linked to the specified organization are returned. If filter\_id is provided, this is ignored. |
| `payload.deal_id` | `integer` | No | — | If supplied, only persons linked to the specified deal are returned. If filter\_id is provided, this is ignored. |
| `payload.updated_since` | `string` | No | — | If set, only persons with an `update_time` later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z. |
| `payload.updated_until` | `string` | No | — | If set, only persons with an `update_time` earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z. |
| `payload.sort_by` | `"id" \| "update_time" \| "add_time"` | No | `"id"` | The field to sort by. Supported fields: `id`, `update_time`, `add_time`. Allowed: `id`, `update_time`, `add_time`. |
| `payload.sort_direction` | `"asc" \| "desc"` | No | `"asc"` | The sorting direction. Supported values: `asc`, `desc`. Allowed: `asc`, `desc`. |
| `payload.include_fields` | `"next_activity_id" \| "last_activity_id" \| "open_deals_count" \| "related_open_deals_count" \| "closed_deals_count" \| "related_closed_deals_count" \| "participant_open_deals_count" \| "participant_closed_deals_count" \| "email_messages_count" \| "activities_count" \| "done_activities_count" \| "undone_activities_count" \| "files_count" \| "notes_count" \| "followers_count" \| "won_deals_count" \| "related_won_deals_count" \| "lost_deals_count" \| "related_lost_deals_count" \| "last_incoming_mail_time" \| "last_outgoing_mail_time" \| "marketing_status" \| "doi_status" \| "smart_bcc_email"` | No | — | Optional comma separated string array of additional fields to include. `marketing_status` and `doi_status` can only be included if the company has marketing app enabled. Allowed: `next_activity_id`, `last_activity_id`, `open_deals_count`, `related_open_deals_count`, `closed_deals_count`, `related_closed_deals_count`, `participant_open_deals_count`, `participant_closed_deals_count`, `email_messages_count`, `activities_count`, `done_activities_count`, `undone_activities_count`, `files_count`, See the live schema for the complete constraint. |
| `payload.custom_fields` | `string` | No | — | Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response. A maximum of 15 keys is allowed. |
| `payload.include_option_labels` | `boolean` | No | — | When provided with a 'true' value, single option and multiple option custom fields values contain objects in the form of '\{ id: number, label: string }' instead of plain id |
| `payload.include_labels` | `boolean` | No | — | When provided with 'true' value, response will include an array of label objects in the form of '\{ id: number, label: string }' |
| `payload.limit` | `integer` | No | — | For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed. |
| `payload.cursor` | `string` | No | — | For pagination, the marker (an opaque string value) representing the first item on the next page |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Returns data about all persons. Fields `ims`, `postal_address`, `notes`, `birthday`, and `job_title` are only included if contact sync is enabled for the company.",
    "properties": {
      "filter_id": {
        "type": "integer",
        "description": "If supplied, only persons matching the specified filter are returned"
      },
      "ids": {
        "type": "string",
        "description": "Optional comma separated string array of up to 100 entity ids to fetch. If filter_id is provided, this is ignored. If any of the requested entities do not exist or are not visible, they are not included in the response."
      },
      "owner_id": {
        "type": "integer",
        "description": "If supplied, only persons owned by the specified user are returned. If filter_id is provided, this is ignored."
      },
      "org_id": {
        "type": "integer",
        "description": "If supplied, only persons linked to the specified organization are returned. If filter_id is provided, this is ignored."
      },
      "deal_id": {
        "type": "integer",
        "description": "If supplied, only persons linked to the specified deal are returned. If filter_id is provided, this is ignored."
      },
      "updated_since": {
        "type": "string",
        "description": "If set, only persons with an `update_time` later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z."
      },
      "updated_until": {
        "type": "string",
        "description": "If set, only persons with an `update_time` earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z."
      },
      "sort_by": {
        "type": "string",
        "description": "The field to sort by. Supported fields: `id`, `update_time`, `add_time`.",
        "default": "id",
        "enum": [
          "id",
          "update_time",
          "add_time"
        ]
      },
      "sort_direction": {
        "type": "string",
        "description": "The sorting direction. Supported values: `asc`, `desc`.",
        "default": "asc",
        "enum": [
          "asc",
          "desc"
        ]
      },
      "include_fields": {
        "type": "string",
        "description": "Optional comma separated string array of additional fields to include. `marketing_status` and `doi_status` can only be included if the company has marketing app enabled.",
        "enum": [
          "next_activity_id",
          "last_activity_id",
          "open_deals_count",
          "related_open_deals_count",
          "closed_deals_count",
          "related_closed_deals_count",
          "participant_open_deals_count",
          "participant_closed_deals_count",
          "email_messages_count",
          "activities_count",
          "done_activities_count",
          "undone_activities_count",
          "files_count",
          "notes_count",
          "followers_count",
          "won_deals_count",
          "related_won_deals_count",
          "lost_deals_count",
          "related_lost_deals_count",
          "last_incoming_mail_time",
          "last_outgoing_mail_time",
          "marketing_status",
          "doi_status",
          "smart_bcc_email"
        ]
      },
      "custom_fields": {
        "type": "string",
        "description": "Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response. A maximum of 15 keys is allowed."
      },
      "include_option_labels": {
        "type": "boolean",
        "description": "When provided with a 'true' value, single option and multiple option custom fields values contain objects in the form of '{ id: number, label: string }' instead of plain id"
      },
      "include_labels": {
        "type": "boolean",
        "description": "When provided with 'true' value, response will include an array of label objects in the form of '{ id: number, label: string }'"
      },
      "limit": {
        "type": "integer",
        "description": "For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed."
      },
      "cursor": {
        "type": "string",
        "description": "For pagination, the marker (an opaque string value) representing the first item on the next page"
      }
    },
    "required": [],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

Standard tool result payload.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `object` | Yes | — | Provider response payload. |
| `result.data.success` | `boolean` | No | — | If the response is successful or not |
| `result.data.data` | `array` | No | — | Persons array |
| `result.data.data[].id` | `integer` | No | — | The ID of the person |
| `result.data.data[].name` | `string` | No | — | The name of the person |
| `result.data.data[].first_name` | `string` | No | — | The first name of the person |
| `result.data.data[].last_name` | `string` | No | — | The last name of the person |
| `result.data.data[].owner_id` | `integer` | No | — | The ID of the user who owns the person |
| `result.data.data[].org_id` | `integer` | No | — | The ID of the organization linked to the person |
| `result.data.data[].add_time` | `string` | No | — | The creation date and time of the person |
| `result.data.data[].update_time` | `string` | No | — | The last updated date and time of the person |
| `result.data.data[].emails` | `array` | No | — | The emails of the person |
| `result.data.data[].emails[].value` | `string` | No | — | The email address of the person |
| `result.data.data[].emails[].primary` | `boolean` | No | — | Whether the email is primary or not |
| `result.data.data[].emails[].label` | `string` | No | — | The email address classification label |
| `result.data.data[].phones` | `array` | No | — | The phones of the person |
| `result.data.data[].phones[].value` | `string` | No | — | The phone number of the person |
| `result.data.data[].phones[].primary` | `boolean` | No | — | Whether the phone number is primary or not |
| `result.data.data[].phones[].label` | `string` | No | — | The phone number classification label |
| `result.data.data[].is_deleted` | `boolean` | No | — | Whether the person is deleted or not |
| `result.data.data[].visible_to` | `integer` | No | — | The visibility of the person |
| `result.data.data[].label_ids` | `array` | No | — | The IDs of labels assigned to the person |
| `result.data.data[].picture_id` | `integer` | No | — | The ID of the picture associated with the person |
| `result.data.data[].postal_address` | `object` | No | — | Postal address of the person, included if contact sync is enabled for the company |
| `result.data.data[].postal_address.value` | `string` | No | — | The full address of the person |
| `result.data.data[].postal_address.country` | `string` | No | — | Country of the person |
| `result.data.data[].postal_address.admin_area_level_1` | `string` | No | — | Admin area level 1 (e.g. state) of the person |
| `result.data.data[].postal_address.admin_area_level_2` | `string` | No | — | Admin area level 2 (e.g. county) of the person |
| `result.data.data[].postal_address.locality` | `string` | No | — | Locality (e.g. city) of the person |
| `result.data.data[].postal_address.sublocality` | `string` | No | — | Sublocality (e.g. neighborhood) of the person |
| `result.data.data[].postal_address.route` | `string` | No | — | Route (e.g. street) of the person |
| `result.data.data[].postal_address.street_number` | `string` | No | — | Street number of the person |
| `result.data.data[].postal_address.subpremise` | `string` | No | — | Subpremise (e.g. apartment/suite number) of the person |
| `result.data.data[].postal_address.postal_code` | `string` | No | — | Postal code of the person |
| `result.data.data[].notes` | `string` | No | — | Contact sync notes of the person, maximum 10 000 characters, included if contact sync is enabled for the company |
| `result.data.data[].im` | `array` | No | — | The instant messaging accounts of the person, included if contact sync is enabled for the company |
| `result.data.data[].im[].value` | `string` | No | — | The instant messaging account of the person |
| `result.data.data[].im[].primary` | `boolean` | No | — | Whether the instant messaging account is primary or not |
| `result.data.data[].im[].label` | `string` | No | — | The instant messaging account classification label |
| `result.data.data[].birthday` | `string` | No | — | The birthday of the person, included if contact sync is enabled for the company |
| `result.data.data[].job_title` | `string` | No | — | The job title of the person, included if contact sync is enabled for the company |
| `result.data.data[].custom_fields` | `record` | No | — | An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error. |
| `result.data.additional_data` | `object` | No | — | The additional data of the list |
| `result.data.additional_data.next_cursor` | `string` | No | — | The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned. |
| `result.meta` | `object` | No | — | Additional response metadata (status, paging). |

<details>
  <summary>Show raw output schema</summary>

  ### Output JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Standard tool result payload.",
    "properties": {
      "data": {
        "type": "object",
        "description": "Provider response payload.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "If the response is successful or not"
          },
          "data": {
            "type": "array",
            "description": "Persons array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "description": "The ID of the person"
                },
                "name": {
                  "type": "string",
                  "description": "The name of the person"
                },
                "first_name": {
                  "type": "string",
                  "description": "The first name of the person"
                },
                "last_name": {
                  "type": "string",
                  "description": "The last name of the person"
                },
                "owner_id": {
                  "type": "integer",
                  "description": "The ID of the user who owns the person"
                },
                "org_id": {
                  "type": "integer",
                  "description": "The ID of the organization linked to the person"
                },
                "add_time": {
                  "type": "string",
                  "description": "The creation date and time of the person"
                },
                "update_time": {
                  "type": "string",
                  "description": "The last updated date and time of the person"
                },
                "emails": {
                  "type": "array",
                  "description": "The emails of the person",
                  "items": {
                    "type": "object",
                    "properties": {
                      "value": {
                        "type": "string",
                        "description": "The email address of the person"
                      },
                      "primary": {
                        "type": "boolean",
                        "description": "Whether the email is primary or not"
                      },
                      "label": {
                        "type": "string",
                        "description": "The email address classification label"
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "phones": {
                  "type": "array",
                  "description": "The phones of the person",
                  "items": {
                    "type": "object",
                    "properties": {
                      "value": {
                        "type": "string",
                        "description": "The phone number of the person"
                      },
                      "primary": {
                        "type": "boolean",
                        "description": "Whether the phone number is primary or not"
                      },
                      "label": {
                        "type": "string",
                        "description": "The phone number classification label"
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "is_deleted": {
                  "type": "boolean",
                  "description": "Whether the person is deleted or not"
                },
                "visible_to": {
                  "type": "integer",
                  "description": "The visibility of the person"
                },
                "label_ids": {
                  "type": "array",
                  "description": "The IDs of labels assigned to the person",
                  "items": {
                    "type": "integer"
                  }
                },
                "picture_id": {
                  "type": "integer",
                  "description": "The ID of the picture associated with the person"
                },
                "postal_address": {
                  "type": "object",
                  "description": "Postal address of the person, included if contact sync is enabled for the company",
                  "properties": {
                    "value": {
                      "type": "string",
                      "description": "The full address of the person"
                    },
                    "country": {
                      "type": "string",
                      "description": "Country of the person"
                    },
                    "admin_area_level_1": {
                      "type": "string",
                      "description": "Admin area level 1 (e.g. state) of the person"
                    },
                    "admin_area_level_2": {
                      "type": "string",
                      "description": "Admin area level 2 (e.g. county) of the person"
                    },
                    "locality": {
                      "type": "string",
                      "description": "Locality (e.g. city) of the person"
                    },
                    "sublocality": {
                      "type": "string",
                      "description": "Sublocality (e.g. neighborhood) of the person"
                    },
                    "route": {
                      "type": "string",
                      "description": "Route (e.g. street) of the person"
                    },
                    "street_number": {
                      "type": "string",
                      "description": "Street number of the person"
                    },
                    "subpremise": {
                      "type": "string",
                      "description": "Subpremise (e.g. apartment/suite number) of the person"
                    },
                    "postal_code": {
                      "type": "string",
                      "description": "Postal code of the person"
                    }
                  },
                  "additionalProperties": false
                },
                "notes": {
                  "type": "string",
                  "description": "Contact sync notes of the person, maximum 10 000 characters, included if contact sync is enabled for the company"
                },
                "im": {
                  "type": "array",
                  "description": "The instant messaging accounts of the person, included if contact sync is enabled for the company",
                  "items": {
                    "type": "object",
                    "properties": {
                      "value": {
                        "type": "string",
                        "description": "The instant messaging account of the person"
                      },
                      "primary": {
                        "type": "boolean",
                        "description": "Whether the instant messaging account is primary or not"
                      },
                      "label": {
                        "type": "string",
                        "description": "The instant messaging account classification label"
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "birthday": {
                  "type": "string",
                  "description": "The birthday of the person, included if contact sync is enabled for the company"
                },
                "job_title": {
                  "type": "string",
                  "description": "The job title of the person, included if contact sync is enabled for the company"
                },
                "custom_fields": {
                  "type": "object",
                  "description": "An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error.",
                  "additionalProperties": true
                }
              },
              "additionalProperties": false
            }
          },
          "additional_data": {
            "type": "object",
            "description": "The additional data of the list",
            "properties": {
              "next_cursor": {
                "type": "string",
                "description": "The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned."
              }
            },
            "additionalProperties": false
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "meta": {
        "type": "object",
        "description": "Additional response metadata (status, paging).",
        "additionalProperties": true
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.

## Related documentation

* [Pipedrive provider guide](https://deepline.com/docs/providers/pipedrive/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.