Pipedrive Tasks API

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: tru

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-tasks-api-openapi.yml