openapi: 3.0.1
info:
title: Pipedrive API v1 Activities ItemSearch API
version: 1.0.0
description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.
'
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: ItemSearch
description: 'Ordered reference objects, pointing to either deals, persons, organizations, leads, products, files or mail attachments.
'
paths:
/itemSearch:
get:
summary: Perform a search from multiple item types
description: Performs a search from your choice of item types and fields.
x-token-cost: 20
operationId: searchItem
tags:
- ItemSearch
security:
- api_key: []
- oauth2:
- search:read
parameters:
- in: query
name: term
required: true
schema:
type: string
description: The search term to look for. Minimum 2 characters (or 1 if using `exact_match`). Please note that the search term has to be URL encoded.
- in: query
name: item_types
schema:
type: string
enum:
- deal
- person
- organization
- product
- lead
- file
- mail_attachment
- project
description: A comma-separated string array. The type of items to perform the search from. Defaults to all.
- in: query
name: fields
schema:
type: string
enum:
- address
- code
- custom_fields
- email
- name
- notes
- phone
- title
- description
description: 'A comma-separated string array. The fields to perform the search from. Defaults to all. Relevant for each item type are:<br> <table> <tr><th><b>Item type</b></th><th><b>Field</b></th></tr> <tr><td>Deal</td><td>`custom_fields`, `notes`, `title`</td></tr> <tr><td>Person</td><td>`custom_fields`, `email`, `name`, `notes`, `phone`</td></tr> <tr><td>Organization</td><td>`address`, `custom_fields`, `name`, `notes`</td></tr> <tr><td>Product</td><td>`code`, `custom_fields`, `name`</td></tr> <tr><td>Lead</td><td>`custom_fields`, `notes`, `title`</td></tr> <tr><td>File</td><td>`name`</td></tr> <tr><td>Mail attachment</td><td>`name`</td></tr> <tr><td>Project</td><td> `custom_fields`, `notes`, `title`, `description` </td></tr> </table> <br> Only the following custom field types are searchable: `address`, `varchar`, `text`, `varchar_auto`, `double`, `monetary` and `phone`. Read more about searching by custom fields <a href="https://support.pipedrive.com/en/article/search-finding-what-you-need#searching-by-custom-fields" target="_blank" rel="noopener noreferrer">here</a>.'
- in: query
name: search_for_related_items
schema:
type: boolean
description: When enabled, the response will include up to 100 newest related leads and 100 newest related deals for each found person and organization and up to 100 newest related persons for each found organization
- in: query
name: exact_match
schema:
type: boolean
description: When enabled, only full exact matches against the given term are returned. It is <b>not</b> case sensitive.
- in: query
name: include_fields
schema:
type: string
enum:
- deal.cc_email
- person.picture
- product.price
description: A comma-separated string array. Supports including optional fields in the results which are not provided by default.
- in: query
name: limit
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 100 is allowed.
schema:
type: integer
example: 100
- in: query
name: cursor
required: false
schema:
type: string
description: For pagination, the marker (an opaque string value) representing the first item on the next page
responses:
'200':
description: Success
content:
application/json:
schema:
title: GetItemSearchResponse
allOf:
- title: baseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
- type: object
title: GetItemSearchResponseData
properties:
data:
type: object
properties:
items:
type: array
description: The array of found items
items:
type: object
title: ItemSearchItem
properties:
result_score:
type: number
description: Search result relevancy
item:
type: object
description: Item
related_items:
type: array
description: The array of related items if `search_for_related_items` was enabled
items:
type: object
title: ItemSearchItem
properties:
result_score:
type: number
description: Search result relevancy
item:
type: object
description: Item
additional_data:
type: object
description: Pagination related data
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.
example:
success: true
data:
items:
- result_score: 1.22724
item:
id: 42
type: deal
title: Sample Deal
value: 53883
currency: USD
status: open
visible_to: 3
owner:
id: 69
stage:
id: 3
name: Demo Scheduled
person:
id: 6
name: Sample Person
organization:
id: 9
name: Sample Organization
address: Dabas, Hungary
custom_fields:
- Sample text
notes:
- Sample note
is_archived: false
- result_score: 0.31335002
item:
id: 9
type: organization
name: Sample Organization
address: Dabas, Hungary
visible_to: 3
owner:
id: 69
custom_fields: []
notes: []
- result_score: 0.29955
item:
id: 6
type: person
name: Sample Person
phones:
- '555123123'
- +372 (55) 123468
- '0231632772'
emails:
- primary@email.com
- secondary@email.com
visible_to: 1
owner:
id: 69
organization:
id: 9
name: Sample Organization
address: Dabas, Hungary
custom_fields:
- Custom Field Text
notes:
- Person note
- result_score: 0.0093
item:
id: 4
type: mail_attachment
name: Sample mail attachment.txt
url: /files/4/download
- result_score: 0.0093
item:
id: 3
type: file
name: Sample file attachment.txt
url: /files/3/download
deal:
id: 42
title: Sample Deal
person:
id: 6
name: Sample Person
organization:
id: 9
name: Sample Organization
address: Dabas, Hungary
- result_score: 0.0011999999
item:
id: 1
type: product
name: Sample Product
code: product-code
visible_to: 3
owner:
id: 69
custom_fields: []
related_items:
- result_score: 0
item:
id: 2
type: deal
title: Other deal
value: 100
currency: USD
status: open
visible_to: 3
owner:
id: 1
stage:
id: 1
name: Lead In
person:
id: 1
name: Sample Person
is_archived: false
additional_data:
next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ
/itemSearch/field:
get:
summary: Perform a search using a specific field from an item type
description: Performs a search from the values of a specific field. Results can either be the distinct values of the field (useful for searching autocomplete field values), or the IDs of actual items (deals, leads, persons, organizations or products).
x-token-cost: 20
operationId: searchItemByField
tags:
- ItemSearch
security:
- api_key: []
- oauth2:
- search:read
parameters:
- in: query
name: term
required: true
schema:
type: string
description: The search term to look for. Minimum 2 characters (or 1 if `match` is `exact`). Please note that the search term has to be URL encoded.
- in: query
name: entity_type
required: true
schema:
type: string
enum:
- deal
- lead
- person
- organization
- product
- project
description: The type of the field to perform the search from
- in: query
name: match
schema:
type: string
default: exact
enum:
- exact
- beginning
- middle
description: The type of match used against the term. The search <b>is</b> case sensitive.<br/><br/> E.g. in case of searching for a value `monkey`, <ul> <li>with `exact` match, you will only find it if term is `monkey`</li> <li>with `beginning` match, you will only find it if the term matches the beginning or the whole string, e.g. `monk` and `monkey`</li> <li>with `middle` match, you will find the it if the term matches any substring of the value, e.g. `onk` and `ke`</li> </ul>.
- in: query
name: field
required: true
schema:
type: string
description: 'The key of the field to search from. The field key can be obtained by fetching the list of the fields using any of the fields'' API GET methods (dealFields, personFields, etc.). Only the following custom field types are searchable: `address`, `varchar`, `text`, `varchar_auto`, `double`, `monetary` and `phone`. Read more about searching by custom fields <a href="https://support.pipedrive.com/en/article/search-finding-what-you-need#searching-by-custom-fields" target="_blank" rel="noopener noreferrer">here</a>.'
- in: query
name: limit
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.
schema:
type: integer
example: 100
- in: query
name: cursor
required: false
schema:
type: string
description: For pagination, the marker (an opaque string value) representing the first item on the next page
responses:
'200':
description: Success
content:
application/json:
schema:
title: GetItemSearchFieldResponse
allOf:
- title: baseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
- type: object
properties:
data:
type: array
description: The array of found fields
items:
type: object
title: ItemSearchItem
properties:
result_score:
type: number
description: Search result relevancy
item:
type: object
description: Item
additional_data:
type: object
description: Pagination related data
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.
example:
success: true
data:
- id: 1
name: Jane Doe
- id: 2
name: John Doe
additional_data:
next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ
components:
securitySchemes:
basic_authentication:
type: http
scheme: basic
description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic <base64(client_id:client_secret)>`.
api_key:
type: apiKey
name: x-api-token
in: header
oauth2:
type: oauth2
description: For more information, see https://pipedrive.readme.io/docs/marketplace-oauth-authorization
flows:
authorizationCode:
authorizationUrl: https://oauth.pipedrive.com/oauth/authorize
tokenUrl: https://oauth.pipedrive.com/oauth/token
refreshUrl: https://oauth.pipedrive.com/oauth/token
scopes:
base: Read settings of the authorized user and currencies in an account
deals:read: Read most of the data about deals and related entities - deal fields, products, followers, participants; all notes, files, filters, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal)
deals:full: Create, read, update and delete deals, its participants and followers; all files, notes, and filters. It also includes read access to deal fields, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal)
mail:read: Read mail threads and messages
mail:full: Read, update and delete mail threads. Also grants read access to mail messages
activities:read: Read activities, its fields and types; all files and filters
activities:full: Create, read, update and delete activities and all files and filters. Also includes read access to activity fields and types
contacts:read: Read the data about persons and organizations, their related fields and followers; also all notes, files, filters
contacts:full: Create, read, update and delete persons and organizations and their followers; all notes, files, filters. Also grants read access to contacts-related fields
products:read: Read products, its fields, files, followers and products connected to a deal
products:full: Create, read, update and delete products and its fields; add products to deals
deal-fields:full: Create, read, update and delete deal fields
product-fields:full: Create, read, update and delete product fields
contact-fields:full: Create, read, update and delete person and organization fields
projects:read: Read projects and its fields, tasks and project templates
projects:full: Create, read, update and delete projects and its fields; add projects templates and project related tasks
users:read: Read data about users (people with access to a Pipedrive account), their permissions, roles and followers
recents:read: Read all recent changes occurred in an account. Includes data about activities, activity types, deals, files, filters, notes, persons, organizations, pipelines, stages, products and users
search:read: Search across the account for deals, persons, organizations, files and products, and see details about the returned results
admin: Allows to do many things that an administrator can do in a Pipedrive company account - create, read, update and delete pipelines and its stages; deal, person and organization fields; activity types; users and permissions, etc. It also allows the app to create webhooks and fetch and delete webhooks that are created by the app
leads:read: Read data about leads and lead labels
leads:full: Create, read, update and delete leads and lead labels
phone-integration: Enables advanced call integration features like logging call duration and other metadata, and play call recordings inside Pipedrive
goals:read: Read data on all goals
goals:full: Create, read, update and delete goals
video-calls: Allows application to register as a video call integration provider and create conference links
messengers-integration: Allows application to register as a messengers integration provider and allows them to deliver incoming messages and their statuses