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:
Item typeField
Deal`custom_fields`, `notes`, `title`
Person`custom_fields`, `email`, `name`, `notes`, `phone`
Organization`address`, `custom_fields`, `name`, `notes`
Product`code`, `custom_fields`, `name`
Lead`custom_fields`, `notes`, `title`
File`name`
Mail attachment`name`
Project `custom_fields`, `notes`, `title`, `description`

Only the following custom field types are searchable: `address`, `varchar`, `text`, `varchar_auto`, `double`, `monetary` and `phone`. Read more about searching by custom fields here.' - 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 not 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 is case sensitive.

E.g. in case of searching for a value `monkey`, . - 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 here.' - 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 `. 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