openapi: 3.0.1
info:
title: Pipedrive API v1 Activities Notes 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: Notes
description: 'Notes are pieces of textual (HTML-formatted) information that can be attached to deals, persons and organizations. Notes are usually displayed in the UI in chronological order – newest first – and in context with other updates regarding the item they are attached to. The maximum note size is approximately 100,000 characters (or 100KB per note).
'
paths:
/notes:
get:
summary: Get all notes
description: Returns all notes.
x-token-cost: 20
operationId: getNotes
tags:
- Notes
security:
- api_key: []
- oauth2:
- deals:read
- deals:full
- contacts:read
- contacts:full
parameters:
- in: query
name: user_id
schema:
type: integer
description: The ID of the user whose notes to fetch. If omitted, notes by all users will be returned.
- in: query
name: lead_id
schema:
type: string
format: uuid
description: The ID of the lead which notes to fetch. If omitted, notes about all leads will be returned.
- in: query
name: deal_id
schema:
type: integer
description: The ID of the deal which notes to fetch. If omitted, notes about all deals will be returned.
- in: query
name: person_id
schema:
type: integer
description: The ID of the person whose notes to fetch. If omitted, notes about all persons will be returned.
- in: query
name: org_id
schema:
type: integer
description: The ID of the organization which notes to fetch. If omitted, notes about all organizations will be returned.
- in: query
name: project_id
schema:
type: integer
description: The ID of the project which notes to fetch. If omitted, notes about all projects will be returned.
- in: query
name: task_id
schema:
type: integer
description: The ID of the task which notes to fetch. If omitted, notes about all tasks will be returned.
- in: query
name: start
description: Pagination start
schema:
type: integer
default: 0
- in: query
name: limit
description: Items shown per page
schema:
type: integer
- in: query
name: sort
schema:
type: string
description: 'The field names and sorting mode separated by a comma (`field_name_1 ASC`, `field_name_2 DESC`). Only first-level field keys are supported (no nested keys). Supported fields: `id`, `user_id`, `deal_id`, `person_id`, `org_id`, `content`, `add_time`, `update_time`.'
- in: query
name: start_date
schema:
type: string
format: date
description: The date in format of YYYY-MM-DD from which notes to fetch
- in: query
name: end_date
schema:
type: string
format: date
description: The date in format of YYYY-MM-DD until which notes to fetch to
- in: query
name: updated_since
description: If set, only notes with an `update_time` later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.
schema:
type: string
format: date-time
example: '2025-01-01T10:20:00Z'
- in: query
name: pinned_to_lead_flag
schema:
title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to lead pinning state
- in: query
name: pinned_to_deal_flag
schema:
title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to deal pinning state
- in: query
name: pinned_to_organization_flag
schema:
title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to organization pinning state
- in: query
name: pinned_to_person_flag
schema:
title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to person pinning state
- in: query
name: pinned_to_project_flag
schema:
title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to project pinning state
- in: query
name: pinned_to_task_flag
schema:
title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to task pinning state
responses:
'200':
description: Get all notes
content:
application/json:
schema:
title: GetNotesResponse
type: object
properties:
success:
type: boolean
description: If the request was successful or not
data:
type: array
description: The array of notes
items:
type: object
title: Note
properties:
id:
type: integer
description: The ID of the note
active_flag:
type: boolean
description: Whether the note is active or deleted
add_time:
type: string
description: The creation date and time of the note
content:
type: string
description: The content of the note in HTML format. Subject to sanitization on the back-end.
deal:
type: object
description: The deal this note is attached to
properties:
title:
type: string
description: The title of the deal this note is attached to
lead_id:
type: string
format: uuid
description: The ID of the lead the note is attached to
deal_id:
type: integer
description: The ID of the deal the note is attached to
last_update_user_id:
type: integer
description: The ID of the user who last updated the note
org_id:
type: integer
description: The ID of the organization the note is attached to
organization:
type: object
description: The organization the note is attached to
properties:
name:
type: string
description: The name of the organization the note is attached to
person:
type: object
description: The person the note is attached to
properties:
name:
type: string
description: The name of the person the note is attached to
person_id:
type: integer
description: The ID of the person the note is attached to
project_id:
type: integer
description: The ID of the project the note is attached to
project:
type: object
description: The project the note is attached to
properties:
title:
type: string
description: The title of the project the note is attached to
task_id:
type: integer
description: The ID of the task the note is attached to
task:
type: object
description: The task the note is attached to
properties:
title:
type: string
description: The title of the task the note is attached to
pinned_to_deal_flag:
type: boolean
description: If true, the results are filtered by note to deal pinning state
pinned_to_organization_flag:
type: boolean
description: If true, the results are filtered by note to organization pinning state
pinned_to_person_flag:
type: boolean
description: If true, the results are filtered by note to person pinning state
pinned_to_project_flag:
type: boolean
description: If true, the results are filtered by note to project pinning state
pinned_to_task_flag:
type: boolean
description: If true, the results are filtered by note to task pinning state
update_time:
type: string
description: The last updated date and time of the note
user:
type: object
description: The user who created the note
properties:
email:
type: string
description: The email of the note creator
icon_url:
type: string
description: The URL of the note creator avatar picture
is_you:
type: boolean
description: Whether the note is created by you or not
name:
type: string
description: The name of the note creator
user_id:
type: integer
description: The ID of the note creator
additional_data:
type: object
properties:
pagination:
title: AdditionalData
type: object
description: The pagination details of the list
properties:
next_start:
type: integer
description: Next pagination start
start:
type: integer
description: Pagination start
limit:
type: integer
description: Items shown per page
more_items_in_collection:
type: boolean
description: If there are more list items in the collection than displayed or not
example:
success: true
data:
- id: 1
active_flag: true
add_time: '2019-12-09 13:59:21'
content: abc
deal:
title: Deal title
lead_id: adf21080-0e10-11eb-879b-05d71fb426ec
deal_id: 1
last_update_user_id: 1
org_id: 1
organization:
name: Organization name
person:
name: Person name
person_id: 1
project_id: 1
project:
title: Project name
pinned_to_lead_flag: false
pinned_to_deal_flag: true
pinned_to_organization_flag: false
pinned_to_person_flag: false
pinned_to_project_flag: false
update_time: '2019-12-09 14:26:11'
user:
email: user@email.com
icon_url: https://iconurl.net/profile_120x120_123.jpg
is_you: true
name: User Name
user_id: 1
additional_data:
pagination:
start: 0
limit: 100
more_items_in_collection: true
next_start: 100
post:
summary: Add a note
description: Adds a new note.
x-token-cost: 10
operationId: addNote
tags:
- Notes
security:
- api_key: []
- oauth2:
- deals:full
- contacts:full
requestBody:
content:
application/json:
schema:
allOf:
- type: object
additionalProperties: true
required:
- content
properties:
content:
type: string
description: The content of the note in HTML format. Subject to sanitization on the back-end.
lead_id:
type: string
format: uuid
description: The ID of the lead the note will be attached to. This property is required unless one of (`deal_id/person_id/org_id/project_id/task_id`) is specified.
deal_id:
type: integer
description: The ID of the deal the note will be attached to. This property is required unless one of (`lead_id/person_id/org_id/project_id/task_id`) is specified.
person_id:
type: integer
description: The ID of the person this note will be attached to. This property is required unless one of (`deal_id/lead_id/org_id/project_id/task_id`) is specified.
org_id:
type: integer
description: The ID of the organization this note will be attached to. This property is required unless one of (`deal_id/lead_id/person_id/project_id/task_id`) is specified.
project_id:
type: integer
description: The ID of the project the note will be attached to. This property is required unless one of (`deal_id/lead_id/person_id/org_id/task_id`) is specified.
task_id:
type: integer
description: The ID of the task the note will be attached to. This property is required unless one of (`deal_id/lead_id/person_id/org_id/project_id`) is specified.
- type: object
properties:
user_id:
type: integer
description: The ID of the user who will be marked as the author of the note. Only an admin can change the author.
add_time:
type: string
description: 'The optional creation date & time of the note in UTC. Can be set in the past or in the future. Format: YYYY-MM-DD HH:MM:SS'
pinned_to_lead_flag:
allOf:
- title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to lead pinning state (`lead_id` is also required)
pinned_to_deal_flag:
allOf:
- title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to deal pinning state (`deal_id` is also required)
pinned_to_organization_flag:
allOf:
- title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to organization pinning state (`org_id` is also required)
pinned_to_person_flag:
allOf:
- title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to person pinning state (`person_id` is also required)
pinned_to_project_flag:
allOf:
- title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to project pinning state (`project_id` is also required)
pinned_to_task_flag:
allOf:
- title: numberBoolean
type: number
enum:
- 0
- 1
description: If set, the results are filtered by note to task pinning state (`task_id` is also required)
responses:
'200':
description: Add, update or get a note
content:
application/json:
schema:
title: UpsertNoteResponse
type: object
properties:
success:
type: boolean
description: If the request was successful or not
data:
type: object
title: Note
properties:
id:
type: integer
description: The ID of the note
active_flag:
type: boolean
description: Whether the note is active or deleted
add_time:
type: string
description: The creation date and time of the note
content:
type: string
description: The content of the note in HTML format. Subject to sanitization on the back-end.
deal:
type: object
description: The deal this note is attached to
properties:
title:
type: string
description: The title of the deal this note is attached to
lead_id:
type: string
format: uuid
description: The ID of the lead the note is attached to
deal_id:
type: integer
description: The ID of the deal the note is attached to
last_update_user_id:
type: integer
description: The ID of the user who last updated the note
org_id:
type: integer
description: The ID of the organization the note is attached to
organization:
type: object
description: The organization the note is attached to
properties:
name:
type: string
description: The name of the organization the note is attached to
person:
type: object
description: The person the note is attached to
properties:
name:
type: string
description: The name of the person the note is attached to
person_id:
type: integer
description: The ID of the person the note is attached to
project_id:
type: integer
description: The ID of the project the note is attached to
project:
type: object
description: The project the note is attached to
properties:
title:
type: string
description: The title of the project the note is attached to
task_id:
type: integer
description: The ID of the task the note is attached to
task:
type: object
description: The task the note is attached to
properties:
title:
type: string
description: The title of the task the note is attached to
pinned_to_deal_flag:
type: boolean
description: If true, the results are filtered by note to deal pinning state
pinned_to_organization_flag:
type: boolean
description: If true, the results are filtered by note to organization pinning state
pinned_to_person_flag:
type: boolean
description: If true, the results are filtered by note to person pinning state
pinned_to_project_flag:
type: boolean
description: If true, the results are filtered by note to project pinning state
pinned_to_task_flag:
type: boolean
description: If true, the results are filtered by note to task pinning state
update_time:
type: string
description: The last updated date and time of the note
user:
type: object
description: The user who created the note
properties:
email:
type: string
description: The email of the note creator
icon_url:
type: string
description: The URL of the note creator avatar picture
is_you:
type: boolean
description: Whether the note is created by you or not
name:
type: string
description: The name of the note creator
user_id:
type: integer
description: The ID of the note creator
example:
success: true
data:
id: 1
active_flag: true
add_time: '2019-12-09 13:59:21'
content: abc
deal:
title: Deal title
lead_id: adf21080-0e10-11eb-879b-05d71fb426ec
deal_id: 1
last_update_user_id: 1
org_id: 1
organization:
name: Organization name
person:
name: Person name
person_id: 1
project_id: 1
project:
title: Project name
pinned_to_lead_flag: false
pinned_to_deal_flag: true
pinned_to_organization_flag: false
pinned_to_person_flag: false
pinned_to_project_flag: false
update_time: '2019-12-09 14:26:11'
user:
email: user@email.com
icon_url: https://iconurl.net/profile_120x120_123.jpg
is_you: true
name: User Name
user_id: 1
/notes/{id}:
delete:
summary: Delete a note
description: Deletes a specific note.
x-token-cost: 6
operationId: deleteNote
tags:
- Notes
security:
- api_key: []
- oauth2:
- deals:full
- contacts:full
parameters:
- in: path
name: id
description: The ID of the note
required: true
schema:
type: integer
responses:
'200':
description: Delete a note
content:
application/json:
schema:
title: DeleteNoteResponse
type: object
properties:
success:
type: boolean
description: If the request was successful or not
data:
type: boolean
description: If the response is successful or not
example:
success: true
data: true
get:
summary: Get one note
description: Returns details about a specific note.
x-token-cost: 2
operationId: getNote
tags:
- Notes
security:
- api_key: []
- oauth2:
- deals:read
- deals:full
- contacts:read
- contacts:full
parameters:
- in: path
name: id
description: The ID of the note
required: true
schema:
type: integer
responses:
'200':
description: Add, update or get a note
content:
application/json:
schema:
title: UpsertNoteResponse
type: object
properties:
success:
type: boolean
description: If the request was successful or not
data:
type: object
title: Note
properties:
id:
type: integer
description: The ID of the note
active_flag:
type: boolean
description: Whether the note is active or deleted
add_time:
type: string
description: The creation date and time of the note
content:
type: string
description: The content of the note in HTML format. Subject to sanitization on the back-end.
deal:
type: object
description: The deal this note is attached to
properties:
title:
type: string
description: The title of the deal this note is attached to
lead_id:
type: string
format: uuid
description: The ID of the lead the note is attached to
deal_id:
type: integer
description: The ID of the deal the note is attached to
last_update_user_id:
type: integer
description: The ID of the user who last updated the note
org_id:
type: integer
description: The ID of the organization the note is attached to
organization:
type: object
description: The organization the note is attached to
properties:
name:
type: string
description: The name of the organization the note is attached to
person:
type: object
description: The person the note is attached to
properties:
name:
type: string
description: The name of the person the note is attached to
person_id:
type: integer
description: The ID of the person the note is attached to
project_id:
type: integer
description: The ID of the project the note is attached to
project:
type: object
description: The project the note is attached to
properties:
title:
type: string
description: The title of the project the note is attached to
task_id:
type: integer
description: The ID of the task the note is attached to
task:
type: object
description: The task the note is attached to
properties:
title:
type: string
description: The title of the task the note is attached to
pinned_to_deal_flag:
type: boolean
description: If true, the results are filtered by note to deal pinning state
pinned_to_organization_flag:
type: boolean
description: If true, the results are filtered by note to organization pinning state
pinned_to_person_flag:
type: boolean
description: If true, the results are filtered by note to person pinning state
pinned_to_project_flag:
type: boolean
description: If true, the results are filtered by note to project pinning state
pinned_to_task_flag:
type: boolean
description: If true, the results are filtered by note to task pinning state
update_time:
type: string
description: The last updated date and time of the note
user:
type: object
description: The user who created the note
properties:
email:
type: string
description: The
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-notes-api-openapi.yml