Docusign TaskLists API

openapi: 3.2.0
info:
  title: DocuSign Rooms API - v2 Task Lists API
  description: An API for an integrator to access the features of DocuSign Rooms
  termsOfService: https://www.docusign.com/company/terms-and-conditions/web
  contact:
    name: DocuSign Developer Center
    url: https://developers.docusign.com
    email: devcenter@docusign.com
  version: v2
servers:
- url: https://rooms.docusign.com/restapi
security:
- Bearer: []
tags:
- name: TaskLists
  description: ''
paths:
  /v2/accounts/{accountId}/rooms/{roomId}/task_lists:
    get:
      tags:
      - TaskLists
      summary: Docusign Gets task lists for a room.
      description: "Returns the task lists associated with a room.\n\n## Permissions\n\nYou must either be a member of the room who has been added to one or more tasks, or have one of the following permissions set to **true:** \n\n- `canAddTasksToAnyTaskLists`\n- `canApplyTaskList`\n- `canRemoveAnyTaskList`\n- `canSubmitTaskList`\n- `canReviewTaskList`\n\n**Note:** If a room has multiple tasks lists, you only see the task lists that contain tasks to which you have been added."
      operationId: TaskLists_GetTaskLists
      parameters:
      - name: roomId
        in: path
        description: The ID of the room.
        required: true
        schema:
          type: integer
          format: int32
      - name: accountId
        in: path
        description: The globally unique identifier (GUID) for the account.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Task lists successfully retrieved.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TaskListSummaryList'
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListSummaryList'
            text/json:
              schema:
                $ref: '#/components/schemas/TaskListSummaryList'
            application/xml:
              schema:
                $ref: '#/components/schemas/TaskListSummaryList'
            text/xml:
              schema:
                $ref: '#/components/schemas/TaskListSummaryList'
        '400':
          description: Bad request. See ErrorCode and Message for details
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Not authorized to make this request.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-ds-methodname: GetTaskLists
      x-ds-method: GetTaskLists
      x-ds-service: TaskLists
      x-ds-in-sdk: true
    post:
      tags:
      - TaskLists
      summary: Docusign Applies a task list to a room.
      description: "Applies a task list to a room, based on the `taskTemplateId` that you specify in the `taskList` request body.\n\n**Note:** You must first create a task list template in the console. You cannot create a task list template by using the API at this time. To get the `taskListTemplateId`, use the \tTaskListTemplates: GetTaskListTemplates method.\n\n## Permissions\n\nYou must have the `canApplyTaskList` permission set to **true.**"
      operationId: TaskLists_CreateTaskList
      parameters:
      - name: roomId
        in: path
        description: The ID of the room.
        required: true
        schema:
          type: integer
          format: int32
      - name: accountId
        in: path
        description: The globally unique identifier (GUID) for the account.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/TaskListForCreate'
          application/json:
            schema:
              $ref: '#/components/schemas/TaskListForCreate'
          text/json:
            schema:
              $ref: '#/components/schemas/TaskListForCreate'
          application/*+json:
            schema:
              $ref: '#/components/schemas/TaskListForCreate'
        required: false
      responses:
        '201':
          description: Task lists successfully created.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TaskList'
            application/json:
              schema:
                $ref: '#/components/schemas/TaskList'
            text/json:
              schema:
                $ref: '#/components/schemas/TaskList'
            application/xml:
              schema:
                $ref: '#/components/schemas/TaskList'
            text/xml:
              schema:
                $ref: '#/components/schemas/TaskList'
        '400':
          description: Bad request. See ErrorCode and Message for details
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Not authorized to make this request.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-ds-methodname: CreateTaskList
      x-ds-method: CreateTaskList
      x-ds-service: TaskLists
      x-ds-in-sdk: true
      x-codegen-request-body-name: body
  /v2/accounts/{accountId}/task_lists/{taskListId}:
    delete:
      tags:
      - TaskLists
      summary: Docusign Deletes a task list from a room.
      description: 'Deletes the specified task list from a room. If there are attached documents, they will remain in the associated room.


        ## Permissions


        You must have the `canRemoveAnyTaskList` permission set to **true.**'
      operationId: TaskLists_DeleteTaskList
      parameters:
      - name: taskListId
        in: path
        description: The ID of the task list.
        required: true
        schema:
          type: integer
          format: int32
      - name: accountId
        in: path
        description: The globally unique identifier (GUID) for the account.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Task list successfully deleted.
          content: {}
        '400':
          description: Bad request. See ErrorCode and Message for details
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Not authorized to make this request.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/json:
              schema:
                $ref: '#/components/schemas/ApiError'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
            text/xml:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-ds-methodname: DeleteTaskList
      x-ds-method: DeleteTaskList
      x-ds-service: TaskLists
      x-ds-in-sdk: true
components:
  schemas:
    TaskListSummary:
      type: object
      properties:
        taskListId:
          type: integer
          description: The ID of the task list.
          format: int32
          readOnly: true
        name:
          type: string
          description: The name of the task list.
          readOnly: true
        taskListTemplateId:
          type: integer
          description: The ID of the task list template.
          format: int32
          readOnly: true
        submittedForReviewDate:
          type: string
          description: The UTC DateTime when the task list was submitted for review.
          format: date-time
          readOnly: true
        approvalDate:
          type: string
          description: The UTC DateTime when the task list was approved.
          format: date-time
          readOnly: true
        rejectedDate:
          type: string
          description: The date on which the reviewer rejected the task list.
          format: date-time
          readOnly: true
        createdDate:
          type: string
          description: 'The UTC date and time when the task list was created. This is a read-only value that the service assigns.


            Example: 2019-07-17T17:45:42.783Z'
          format: date-time
          readOnly: true
        approvedByUserId:
          type: integer
          description: The ID of the user who approved the task list.
          format: int32
          readOnly: true
        rejectedByUserId:
          type: integer
          description: The ID of the user who rejected the task list.
          format: int32
          readOnly: true
        comment:
          type: string
          description: Contains a user comment about the task list.
          readOnly: true
      description: Contains information about a task list.
      x-ds-definition-name: TaskListSummary
      x-ms-summary: Contains information about a task list.
    TaskList:
      type: object
      properties:
        taskListId:
          type: integer
          description: The ID of the task list.
          format: int32
        name:
          type: string
          description: The name of the task list.
        taskListTemplateId:
          type: integer
          description: The ID of the task list template used to create the task list.
          format: int32
        submittedForReviewDate:
          type: string
          description: The UTC DateTime when the task list was submitted for review.
          format: date-time
        approvalDate:
          type: string
          description: The UTC DateTime when the task list was approved.
          format: date-time
        rejectedDate:
          type: string
          description: 'The UTC DateTime when the reviewer rejected the task list. '
          format: date-time
        createdDate:
          type: string
          description: 'The UTC date and time when the task list was created. This is a read-only value that the service assigns.


            Example: 2019-07-17T17:45:42.783Z'
          format: date-time
        approvedByUserId:
          type: integer
          description: The ID of the user who approved the task list.
          format: int32
        rejectedByUserId:
          type: integer
          description: The ID of the user who rejected the task list.
          format: int32
        comment:
          type: string
          description: Contains a comment about the task list.
        tasks:
          type: array
          description: A list of tasks in the task list.
          items:
            $ref: '#/components/schemas/TaskSummary'
      description: This response object contains details about the new task list.
      x-ds-definition-name: TaskList
      x-ms-summary: This response object contains details about the new task list.
    TaskSummary:
      type: object
      properties:
        taskId:
          type: integer
          description: The ID of the task list.
          format: int32
        name:
          type: string
          description: The name of the task list.
        requiresApproval:
          type: boolean
          description: When **true,** the task must be completed and reviewed before it can be closed.
        dueDateTypeId:
          type: string
          description: The ID of the due date type (such as Actual Close Date or Contract Date).
        dueDateOffset:
          type: integer
          description: The number of days before or after the due date (specified by the `dueDateTypeId`) within which the task must be completed. A negative number indicates that the task must be completed within a certain number of days before the due date. A positive number indicates that the task must be completed within a certain number of days after the due date.
          format: int32
        fixedDueDate:
          type: string
          description: 'A specific calendar due date for the task.


            In the API, this value is a UTC DateTime that does not actually include a time.


            Example: 2019-07-17T00:00:00.000Z'
          format: date-time
        ownerUserId:
          type: integer
          description: The ID of the user who owns the task.
          format: int32
        completionDate:
          type: string
          description: 'The UTC DateTime when the task was completed.


            Example: 2019-07-17T17:45:42.783Z'
          format: date-time
        approvalDate:
          type: string
          description: 'The UTC DateTime when the task was approved.


            Example: 2019-07-17T17:45:42.783Z'
          format: date-time
        rejectedDate:
          type: string
          description: The date on which the reviewer rejected the task.
          format: date-time
        createdDate:
          type: string
          description: "\t\nThe UTC date and time when the task was created. This is a read-only value that the service assigns.\n\nExample: 2019-07-17T17:45:42.783Z"
          format: date-time
        isDocumentTask:
          type: boolean
          description: When **true,** the task is associated with a document.
        requiresReview:
          type: boolean
          description: When **true,** the task is optional. If the task is completed (if a document is added or the task is marked complete), it must be reviewed before it can be closed.
      description: Contains information about a task list.
      x-ds-definition-name: TaskSummary
      x-ms-summary: Contains information about a task list.
    TaskListSummaryList:
      type: object
      properties:
        taskListSummaries:
          type: array
          description: A list of task list summaries.
          items:
            $ref: '#/components/schemas/TaskListSummary'
      description: Contains a list of task list summaries.
      x-ds-definition-name: TaskListSummaryList
      x-ms-summary: Contains a list of task list summaries.
    TaskListForCreate:
      type: object
      properties:
        taskListTemplateId:
          type: integer
          description: (Required) The ID of the task list template.
          format: int32
      description: Contains information about the task list template to use to create the new task list.
      x-ds-definition-name: TaskListForCreate
      x-ms-summary: Contains information about the task list template to use to create the new task list.
    ApiError:
      type: object
      properties:
        errorCode:
          type: string
          description: The code associated with the error condition.
        message:
          type: string
          description: A brief message describing the error condition.
        referenceId:
          type: string
          description: ''
      description: This object describes errors that occur. It is valid only for responses and ignored in requests.
      x-ds-definition-name: ApiError
      x-ms-summary: This object describes errors that occur. It is valid only for responses and ignored in requests.
  securitySchemes:
    Bearer:
      type: apiKey
      description: 'JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"'
      name: Authorization
      in: header
externalDocs:
  description: Rooms API Reference
  url: https://developers.docusign.com/docs/rooms-api/reference/
x-ds-categories:
- name: Accounts
  summary: Information about accounts.
  description: Information about accounts.
- name: Documents
  summary: Information about documents.
  description: Information about documents.
- name: ESignPermissionProfiles
  summary: A permission profile is a standard set of user permissions that you can apply to individual users or the users in a group. This functionality makes it easier to manage permissions for a large number of users.
  description: 'When you create or invite a new member in Rooms, the system creates an eSignature account for the member at the same time. This section shows you how to retrieve a list of eSignature permission profiles that the current user can assign to a new member.


    You can use the API only to retrieve and assign eSignature permission profiles. You create and modify permission profiles in the DocuSign console.'
- name: Fields
  summary: This section shows you how to retrieve a specific field set. This is a set of fields that can appear on a room's **Details** tab.
  description: Information about field sets.
- name: Forms
  summary: 'The Forms feature of DocuSign Rooms for Real Estate enables provides access to standard industry association forms that you can add to rooms.


    **Note:** Forms is not a default feature and is currently only available in Rooms for Real Estate. To request access to Forms, contact your DocuSign Account Manager.


    '
  description: "## Form groups\n\nWith the appropriate permissions, form administrators at your company can create form groups, or curated set of forms gathered from the association **form libraries** to which DocuSign provides access. Form groups enable agents to know which forms to add to rooms based on the type of transaction they are working on. When creating groups, administrators can make certain forms required, ensuring compliance. If you don't create groups, agents will have to choose forms they need from a list of association forms.\n\n## Permissions\n\nTo manage forms, you must have the `canManageFormGroups` permission, which enables you to access the **Forms** tab in **Admin.** For all other roles, assign permissions based on how these users will be working with forms. If no form permissions are enabled for these roles, users cannot add forms to rooms.\n\nForm administrators must have the `canManageFormGroups` permission assigned to their user role. This gives them access to the **Forms** tab in **Admin.** However, you should also consider the user's access level. For example, if the user has access to specific offices, they can only administer form groups for those offices. \n"
- name: GlobalResources
  summary: The Global Resources category organizes resource that are used throughout the Rooms API. You typically use these resources when you create or update a room, region, office, or user.
  description: 'This section shows you how to retrieve the following Global Resources:


    - Activity Types

    - Closing Statuses

    - Contact Sides

    - Countries

    - Currencies

    - Financing Types

    - Origins of Leads

    - Property Types

    - Room Contact Types

    - Seller Decision Types

    - Special Circumstances Types

    - States

    - Task Date Types

    - Task Responsibility Types

    - Time Zones

    - Transaction Sides'
- name: Offices
  summary: You can use the API to manage offices in your Rooms account.
  description: This section shows you how to create and manage offices.
- name: Regions
  summary: You can use the API to manage regions associated with your Rooms account.
  description: This section shows you how to create and manage regions for a Rooms account.
- name: Roles
  summary: 'The Roles resource enables you to easily manage user permissions. '
  description: 'Each role is associated with specific permissions. Each new member is assigned a role when you create them, automatically granting them the permissions associated with that role.


    Roles use the following permission types to control the actions that users can perform:


    - Room

    - Room Details

    - Documents

    - Envelopes

    - Member Management

    - Company Settings


    Rooms enables you to configure custom roles containing permissions that make sense for your company. Because each new member is assigned a role, you must set up these roles before you can invite members to join your account.


    Permissions for roles are tied to the `roleId` property and not yet exposed. You can learn more about these permission types and configure them in the web application.


    ### Internal and External Roles


    In Rooms, a role can be either internal or external. You assign internal roles to people inside your company. You assign external roles to people outside your company when you invite them to a room.


    Each member inside your company has a default company role. However, they can also be assigned additional roles with different permissions on a per-room basis. Regardless of the member''s default company role, what they can do in a room is entirely controlled by their role in that particular room.

    '
- name: Rooms
  summary: This section shows you how to create and mange rooms. In Rooms for Real Estate, a room is a collaborative digital space corresponding to a specific property. In Rooms for Mortgages, a room corresponds to a specific loan.
  description: 'A room can hold documents, envelopes, a list of tasks comprising a workflow, and other related information. You can invite others to this space and assign them permissions on a per-room basis. The documentation in this section shows you how to perform these and other tasks.

    '
- name: RoomTemplates
  summary: 'Room templates enable your company to standardize the new rooms that users create. '
  description: This section shows you how to retrieve room templates. You can perform additional room template tasks in the console.
- name: TaskLists
  summary: The TaskLists resource helps you keep track of the documents and activities you must complete before you can close a room.
  description: Your administrator may also have created custom task list templates that can be added to rooms. If your administrator created room templates, those room templates may include task lists for you to use.
- name: Users
  summary: The Users resource provides methods that enable you to add, update, delete, and manage users.
  description: A user is a person who is either added to a room (as a participant), or who is a member of a company. This section shows you how to manage users, including how to update and delete National Association of REALTORS® member numbers.
x-original-swagger-version: '2.0'