openapi: 3.0.1
info:
  title: Pipedrive API v1 Activities Tasks 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: Tasks
  description: 'Tasks represent actions that need to be completed and must be associated with a project. Tasks have an optional due date, can be assigned to a user and can have subtasks.

    '
paths:
  /tasks:
    get:
      summary: Get all tasks
      description: Returns all tasks. This is a cursor-paginated endpoint. For more information, please refer to our documentation on <a href="https://pipedrive.readme.io/docs/core-api-concepts-pagination" target="_blank" rel="noopener noreferrer">pagination</a>.
      x-token-cost: 20
      operationId: getTasks
      tags:
      - Tasks
      security:
      - api_key: []
      - oauth2:
        - projects:read
        - projects:full
      parameters:
      - 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
      - in: query
        name: limit
        description: For pagination, the limit of entries to be returned. If not provided, up to 500 items will be returned.
        schema:
          type: integer
          example: 500
      - in: query
        name: assignee_id
        required: false
        schema:
          type: integer
        description: If supplied, only tasks that are assigned to this user are returned
      - in: query
        name: project_id
        required: false
        schema:
          type: integer
        description: If supplied, only tasks that are assigned to this project are returned
      - in: query
        name: parent_task_id
        required: false
        schema:
          type: integer
        description: If `null` is supplied then only parent tasks are returned. If integer is supplied then only subtasks of a specific task are returned. By default all tasks are returned.
      - in: query
        name: done
        required: false
        schema:
          title: numberBoolean
          type: number
          enum:
          - 0
          - 1
        description: Whether the task is done or not. `0` = Not done, `1` = Done. If not omitted then returns both done and not done tasks.
      responses:
        '200':
          description: A list of tasks.
          content:
            application/json:
              schema:
                title: GetTasksResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      title: TaskResponseObject
                      type: object
                      allOf:
                      - type: object
                        properties:
                          id:
                            type: integer
                            description: The ID of the task, generated when the task was created
                      - title: updateProjectRequest
                        type: object
                        allOf:
                        - type: object
                          properties:
                            title:
                              description: The title of the task
                              type: string
                            project_id:
                              description: The ID of the project this task is associated with
                              type: number
                        - type: object
                          properties:
                            description:
                              description: The description of the task
                              type: string
                            parent_task_id:
                              description: The ID of a parent task. Can not be ID of a task which is already a subtask.
                              type: number
                            assignee_id:
                              type: number
                              description: The ID of the user assigned to the task. When the `assignee_id` field is updated, the `assignee_ids` field value will be overwritten by the `assignee_id` field value.
                            assignee_ids:
                              type: array
                              items:
                                type: number
                              maxItems: 10
                              uniqueItems: true
                              description: The IDs of users assigned to the task. When the `assignee_ids` field is updated, the `assignee_id` field value will be set to the first value of the `assignee_ids` field, or `null` if the list is empty.
                            done:
                              description: Whether the task is done or not. 0 = Not done, 1 = Done.
                              allOf:
                              - title: numberBoolean
                                type: number
                                enum:
                                - 0
                                - 1
                            due_date:
                              description: 'The due date of the task. Format: YYYY-MM-DD.'
                              type: string
                              format: date
                        - type: object
                          properties:
                            creator_id:
                              type: number
                              description: The creator of a task
                            add_time:
                              type: string
                              description: 'The creation date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                            update_time:
                              type: string
                              description: 'The update date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                            marked_as_done_time:
                              type: string
                              description: 'The marked as done date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                  additional_data:
                    description: The additional data of the list
                    type: object
                    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
                  title: Task 1
                  creator_id: 2
                  description: Task description
                  done: 0
                  due_date: '2023-10-11'
                  parent_task_id: 2
                  assignee_id: 2
                  assignee_ids:
                  - 2
                  - 3
                  - 4
                  add_time: '2023-09-14 08:14:40.288'
                  update_time: '2023-09-14 08:14:40.288'
                  marked_as_done_time: '2023-09-22 08:14:40.288'
                  project_id: 1
                additional_data:
                  next_cursor: eyJhY3Rpdml0aWVzIjoyN30
    post:
      summary: Add a task
      description: Adds a new task.
      x-token-cost: 10
      operationId: addTask
      tags:
      - Tasks
      security:
      - api_key: []
      - oauth2:
        - projects:full
      requestBody:
        content:
          application/json:
            schema:
              title: addTaskRequest
              allOf:
              - title: requiredPostProjectParameters
                type: object
                required:
                - title
                - project_id
                properties:
                  title:
                    description: The title of the task
                    type: string
                  project_id:
                    description: The ID of a project
                    type: number
              - type: object
                properties:
                  description:
                    description: The description of the task
                    type: string
                  parent_task_id:
                    description: The ID of a parent task. Can not be ID of a task which is already a subtask.
                    type: number
                  assignee_id:
                    type: number
                    description: The ID of the user assigned to the task. When the `assignee_id` field is updated, the `assignee_ids` field value will be overwritten by the `assignee_id` field value.
                  assignee_ids:
                    type: array
                    items:
                      type: number
                    maxItems: 10
                    uniqueItems: true
                    description: The IDs of users assigned to the task. When the `assignee_ids` field is updated, the `assignee_id` field value will be set to the first value of the `assignee_ids` field, or `null` if the list is empty.
                  done:
                    description: Whether the task is done or not. 0 = Not done, 1 = Done.
                    allOf:
                    - title: numberBoolean
                      type: number
                      enum:
                      - 0
                      - 1
                  due_date:
                    description: 'The due date of the task. Format: YYYY-MM-DD.'
                    type: string
                    format: date
      responses:
        '201':
          description: Created task.
          content:
            application/json:
              schema:
                title: AddTaskResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    title: TaskResponseObject
                    type: object
                    allOf:
                    - type: object
                      properties:
                        id:
                          type: integer
                          description: The ID of the task, generated when the task was created
                    - title: updateProjectRequest
                      type: object
                      allOf:
                      - type: object
                        properties:
                          title:
                            description: The title of the task
                            type: string
                          project_id:
                            description: The ID of the project this task is associated with
                            type: number
                      - type: object
                        properties:
                          description:
                            description: The description of the task
                            type: string
                          parent_task_id:
                            description: The ID of a parent task. Can not be ID of a task which is already a subtask.
                            type: number
                          assignee_id:
                            type: number
                            description: The ID of the user assigned to the task. When the `assignee_id` field is updated, the `assignee_ids` field value will be overwritten by the `assignee_id` field value.
                          assignee_ids:
                            type: array
                            items:
                              type: number
                            maxItems: 10
                            uniqueItems: true
                            description: The IDs of users assigned to the task. When the `assignee_ids` field is updated, the `assignee_id` field value will be set to the first value of the `assignee_ids` field, or `null` if the list is empty.
                          done:
                            description: Whether the task is done or not. 0 = Not done, 1 = Done.
                            allOf:
                            - title: numberBoolean
                              type: number
                              enum:
                              - 0
                              - 1
                          due_date:
                            description: 'The due date of the task. Format: YYYY-MM-DD.'
                            type: string
                            format: date
                      - type: object
                        properties:
                          creator_id:
                            type: number
                            description: The creator of a task
                          add_time:
                            type: string
                            description: 'The creation date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          update_time:
                            type: string
                            description: 'The update date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          marked_as_done_time:
                            type: string
                            description: 'The marked as done date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                  additional_data:
                    type: object
                    nullable: true
                    example: null
              example:
                success: true
                data:
                  id: 1
                  title: Task 1
                  creator_id: 2
                  description: Task description
                  done: 0
                  due_date: '2023-10-11'
                  parent_task_id: 2
                  assignee_id: 2
                  assignee_ids:
                  - 2
                  - 3
                  - 4
                  add_time: '2023-09-14 08:14:40.288'
                  update_time: '2023-09-14 08:14:40.288'
                  marked_as_done_time: '2023-09-22 08:14:40.288'
                  project_id: 1
                additional_data: null
  /tasks/{id}:
    get:
      summary: Get details of a task
      description: Returns the details of a specific task.
      x-token-cost: 2
      operationId: getTask
      tags:
      - Tasks
      security:
      - api_key: []
      - oauth2:
        - projects:read
        - projects:full
      parameters:
      - in: path
        name: id
        description: The ID of the task
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Get a task.
          content:
            application/json:
              schema:
                title: GetTaskResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    title: TaskResponseObject
                    type: object
                    allOf:
                    - type: object
                      properties:
                        id:
                          type: integer
                          description: The ID of the task, generated when the task was created
                    - title: updateProjectRequest
                      type: object
                      allOf:
                      - type: object
                        properties:
                          title:
                            description: The title of the task
                            type: string
                          project_id:
                            description: The ID of the project this task is associated with
                            type: number
                      - type: object
                        properties:
                          description:
                            description: The description of the task
                            type: string
                          parent_task_id:
                            description: The ID of a parent task. Can not be ID of a task which is already a subtask.
                            type: number
                          assignee_id:
                            type: number
                            description: The ID of the user assigned to the task. When the `assignee_id` field is updated, the `assignee_ids` field value will be overwritten by the `assignee_id` field value.
                          assignee_ids:
                            type: array
                            items:
                              type: number
                            maxItems: 10
                            uniqueItems: true
                            description: The IDs of users assigned to the task. When the `assignee_ids` field is updated, the `assignee_id` field value will be set to the first value of the `assignee_ids` field, or `null` if the list is empty.
                          done:
                            description: Whether the task is done or not. 0 = Not done, 1 = Done.
                            allOf:
                            - title: numberBoolean
                              type: number
                              enum:
                              - 0
                              - 1
                          due_date:
                            description: 'The due date of the task. Format: YYYY-MM-DD.'
                            type: string
                            format: date
                      - type: object
                        properties:
                          creator_id:
                            type: number
                            description: The creator of a task
                          add_time:
                            type: string
                            description: 'The creation date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          update_time:
                            type: string
                            description: 'The update date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          marked_as_done_time:
                            type: string
                            description: 'The marked as done date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                  additional_data:
                    type: object
                    nullable: true
                    example: null
              example:
                success: true
                data:
                  id: 1
                  title: Task 1
                  creator_id: 2
                  description: Task description
                  done: 0
                  due_date: '2023-10-11'
                  parent_task_id: 2
                  assignee_id: 2
                  assignee_ids:
                  - 2
                  - 3
                  - 4
                  add_time: '2023-09-14 08:14:40.288'
                  update_time: '2023-09-14 08:14:40.288'
                  marked_as_done_time: '2023-09-22 08:14:40.288'
                  project_id: 1
                additional_data: null
    put:
      summary: Update a task
      description: Updates a task.
      x-token-cost: 10
      operationId: updateTask
      tags:
      - Tasks
      security:
      - api_key: []
      - oauth2:
        - projects:full
      parameters:
      - in: path
        name: id
        description: The ID of the task
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              title: updateProjectRequest
              type: object
              allOf:
              - type: object
                properties:
                  title:
                    description: The title of the task
                    type: string
                  project_id:
                    description: The ID of the project this task is associated with
                    type: number
              - type: object
                properties:
                  description:
                    description: The description of the task
                    type: string
                  parent_task_id:
                    description: The ID of a parent task. Can not be ID of a task which is already a subtask.
                    type: number
                  assignee_id:
                    type: number
                    description: The ID of the user assigned to the task. When the `assignee_id` field is updated, the `assignee_ids` field value will be overwritten by the `assignee_id` field value.
                  assignee_ids:
                    type: array
                    items:
                      type: number
                    maxItems: 10
                    uniqueItems: true
                    description: The IDs of users assigned to the task. When the `assignee_ids` field is updated, the `assignee_id` field value will be set to the first value of the `assignee_ids` field, or `null` if the list is empty.
                  done:
                    description: Whether the task is done or not. 0 = Not done, 1 = Done.
                    allOf:
                    - title: numberBoolean
                      type: number
                      enum:
                      - 0
                      - 1
                  due_date:
                    description: 'The due date of the task. Format: YYYY-MM-DD.'
                    type: string
                    format: date
      responses:
        '200':
          description: Updated task.
          content:
            application/json:
              schema:
                title: UpdateTaskResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    title: TaskResponseObject
                    type: object
                    allOf:
                    - type: object
                      properties:
                        id:
                          type: integer
                          description: The ID of the task, generated when the task was created
                    - title: updateProjectRequest
                      type: object
                      allOf:
                      - type: object
                        properties:
                          title:
                            description: The title of the task
                            type: string
                          project_id:
                            description: The ID of the project this task is associated with
                            type: number
                      - type: object
                        properties:
                          description:
                            description: The description of the task
                            type: string
                          parent_task_id:
                            description: The ID of a parent task. Can not be ID of a task which is already a subtask.
                            type: number
                          assignee_id:
                            type: number
                            description: The ID of the user assigned to the task. When the `assignee_id` field is updated, the `assignee_ids` field value will be overwritten by the `assignee_id` field value.
                          assignee_ids:
                            type: array
                            items:
                              type: number
                            maxItems: 10
                            uniqueItems: true
                            description: The IDs of users assigned to the task. When the `assignee_ids` field is updated, the `assignee_id` field value will be set to the first value of the `assignee_ids` field, or `null` if the list is empty.
                          done:
                            description: Whether the task is done or not. 0 = Not done, 1 = Done.
                            allOf:
                            - title: numberBoolean
                              type: number
                              enum:
                              - 0
                              - 1
                          due_date:
                            description: 'The due date of the task. Format: YYYY-MM-DD.'
                            type: string
                            format: date
                      - type: object
                        properties:
                          creator_id:
                            type: number
                            description: The creator of a task
                          add_time:
                            type: string
                            description: 'The creation date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          update_time:
                            type: string
                            description: 'The update date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          marked_as_done_time:
                            type: string
                            description: 'The marked as done date and time of the task in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                  additional_data:
                    type: object
                    nullable: true
                    example: null
              example:
                success: true
                data:
                  id: 1
                  title: Task 1
                  creator_id: 2
                  description: Task description
                  done: 0
                  due_date: '2023-10-11'
                  parent_task_id: 2
                  assignee_id: 2
                  assignee_ids:
                  - 2
                  - 3
                  - 4
                  add_time: '2023-09-14 08:14:40.288'
                  update_time: '2023-09-14 08:14:40.288'
                  marked_as_done_time: '2023-09-22 08:14:40.288'
                  project_id: 1
                additional_data: null
    delete:
      summary: Delete a task
      description: Marks a task as deleted. If the task has subtasks then those will also be deleted.
      x-token-cost: 6
      operationId: deleteTask
      tags:
      - Tasks
      security:
      - api_key: []
      - oauth2:
        - projects:full
      parameters:
      - in: path
        name: id
        description: The ID of the task
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted task.
          content:
            application/json:
              schema:
                title: DeleteTaskResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    title: deleteTask
                    type: object
                    properties:
                      success:
                        type: boolean
                        description: If the request was successful or not
                      data:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: The ID of the task that was deleted
                  additional_data:
                    type: object
                    nullable: true
                    example: null
              example:
                success: true
                data:
                  id: 1
                additional_data: null
    patch:
      summary: Update a task
      description: Updates a task.
      x-token-cost: 5
      operationId: updateTask
      tags:
      - Tasks
      security:
      - api_key: []
      - oauth2:
        - projects:full
      parameters:
      - in: path
        name: id
        description: The ID of the task
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              title: updateTaskRequest
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: The title of the task
                project_id:
                  type: integer
                  description: The ID of the project this task is associated with
                parent_task_id:
                  type: integer
                  nullable: true
                  description: The ID of the parent task. Cannot be the ID of a task that is already a subtask.
                description:
                  type: string
                  nullable: true
                  description: The description of the task
                done:
                  type: integer
                  enum:
                  - 0
                  - 1
                  description: Whether the task is done or not. `0` = Not done, `1` = Done.
                milestone:
                  type: integer
                  enum:
                  - 0
                  - 1
                  description: Whether the task is a milestone or not. `0` = Not a milestone, `1` = Milestone.
                due_date:
                  type: string
                  format: date
                  nullable: true
                  description: 'The due date of the task. Format: YYYY-MM-DD.'
                start_date:
                  type: string
                  format: date
                  nullable: true
                  description: 'The start date of the task. Format: YYYY-MM-DD.'
                assignee_id:
                  type: integer
                  nullable: true
                  description: The ID of the user assigned to the task. When set, the `assignee_ids` field will be overwritten with this value.
                assignee_ids:
                  type: array
                  items:
                    type: integer
                  maxItems: 10
                  description: The IDs of users assigned to the task. When set, the `assignee_id` field will be set to the first value in this array, or `null` if empty.
                priority:
                  type: integer
                  minimum: 0
                  nullable: true
                  description: The priority of the task
      responses:
        '200':
          description: Updated task.
          content:
            application/json:
              schema:
                title: UpdateTaskResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the response is successful or not
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: The ID of the task
                      title:
                        type: string
                        minLength: 1
                        maxLength: 255
                        description: The title of the task
                      creator_id:
                        type: integer
                        description: The ID of the user who created the task
                      description:
                        type: string
                        nullable: true
                        description: The description of the task
                      project_id:
                        type: integer
                        description: The ID of the project this task is associated with
                      is_done:
                        type: boolean
                        description: Whether the task is done or not.
                      is_milestone:
                        type: boolean
                        description: Whether the task is a milestone or not.
                      due_date:
                        type: string
                        format: date
                        nullable: true
                        description: 'The due date of the task. Format: YYYY-MM-DD.'
                      start_date:
                        type: string
                        format: date
                        nullable: true
                        description: 'The start date of the task. Format: YYYY-MM-DD.'
                      parent_task_id:
                        type: integer
                        nullable: true
                        description: The ID of the parent task. If `null`, the task is a root-level task.
                      assignee_ids:
                        type: array
                        items:
                          type: integer
                        description: The IDs of users assigned to the task
                      priority:
                        type: integer
                        minimum: 0
                        nullable: true
                        description: The priority of the task
                      add_time:
                        type: string
                        description: The creation date and time of the task in ISO 8601 format
                      update_time:
                        type: string
                        description: The update date and time of the task in ISO 8601 format
                      marked_as_done_time:
                        type: string
                        nullable: true
                        description: The date and time the task was marked as done in ISO 8601 format
                  additional_data:
                    type: object
                    nullable: true
                    example: null
              example:
                success: true
                data:
                  id: 1
                  title: Task 1
                  creator_id: 2
                  description: Task description
                  project_id: 1
                  is_done: false
                  is_milestone: false
                  due_date: '2026-10-11'
                  start_date: '2026-09-01'
                  parent_task_id: null
                  assignee_ids:
                  - 2
                  - 3
                  priority: null
                  add_time: '2026-09-14T08:14:40.000Z'
                  update_time: '2026-09-14T08:14:40.000Z'
                  marked_as_done_time: null
                additional_data: null
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