Forsta Survey Tasks API

openapi: 3.2.0
info:
  title: Decipher Rest Survey Tasks API
  version: '1.0'
  description: The Decipher REST API allows comprehensive automation of your private or shared Decipher instance.
servers:
- url: https://{server}/api/v1
  description: Replace server with your instance domain.
  variables:
    server:
      default: selfserve.decipherinc.com
      description: Server domain
security:
- APIKey: []
tags:
- name: Survey Tasks
paths:
  /surveys/{survey}/tasks:
    get:
      operationId: getSurveyTasks
      summary: Get survey tasks
      description: List tasks for a survey.
      tags:
      - Survey Tasks
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: status
        in: query
        description: Status the tasks should be filtered by.
        required: false
        schema:
          type: string
          enum:
          - incomplete
          - completed
          - confirmed
          example: incomplete
      - name: orphaned
        in: query
        description: "Omit to include all tasks. Pass `false` to exclude orphaned tasks, or \n`true` to exclude non-orphaned tasks.\n"
        required: false
        schema:
          type: boolean
          example: true
      - name: elements
        in: query
        description: List of element labels the tasks should be filtered by.
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
          example:
          - q1
          - cm1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: List of tasks for the survey.
                items:
                  $ref: '#/components/schemas/surveyTask'
              example:
              - status: incomplete
                description: '<p>Task 1: Delete r2</p>'
                task_id: 1
                comments:
                - created_on: '2022-03-08T22:23:06Z'
                  comment_id: 1
                  email: user2@example.com
                  description: <p>Comment for Task 1</p>
                label: q1
                created_on: '2022-03-08T22:35:42Z'
                path: selfserve/1a/123456
                email: user1@example.com
                orphaned: false
              - status: completed
                description: '<p>Task 2: Change cm1</p>'
                task_id: 2
                comments:
                - created_on: '2022-03-08T22:23:06Z'
                  comment_id: 1
                  email: user3@example.com
                  description: <p>First comment for Task 2</p>
                - created_on: '2022-03-08T22:23:06Z'
                  comment_id: 2
                  email: user1@example.com
                  description: <p>Second comment for Task 2</p>
                label: cm1
                created_on: '2022-03-08T22:35:42Z'
                path: selfserve/1a/123456
                email: user2@example.com
                orphaned: false
        '400':
          description: Invalid status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: 'argument ''status'': must be one of completed,confirmed,incomplete'
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 400
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
    post:
      operationId: createSurveyTask
      summary: Create survey task
      description: Create a task for a survey.
      tags:
      - Survey Tasks
      parameters:
      - $ref: '#/components/parameters/survey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                element_label:
                  type: string
                  description: 'The label of the question or comment element the task should be created for.

                    '
                  example: q1
                description:
                  type: string
                  description: Description of the task in plain text or HTML format.
                  example: <p>Task description</p>
                status:
                  type: string
                  enum:
                  - incomplete
                  - completed
                  - confirmed
                  description: Status of the task - defaults to incomplete if not specified.
                  example: incomplete
              required:
              - element_label
              - description
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/surveyTask'
              example:
                status: incomplete
                description: <p>Task description</p>
                task_id: 1
                comments: []
                label: q1
                created_on: '2022-03-08T22:35:42Z'
                path: selfserve/1a/123456
                email: user1@example.com
                orphaned: false
        '400':
          description: Empty/missing description or invalid status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: Description must not be empty
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 400
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
    delete:
      operationId: deleteSurveyTask
      summary: Delete survey task
      description: Delete a task from a survey.
      tags:
      - Survey Tasks
      parameters:
      - $ref: '#/components/parameters/survey'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  task_id:
                    description: The id of the task to be deleted.
                    type: integer
                    example: 1
                required:
                - task_id
              - type: object
                properties:
                  comment_id:
                    description: The id of the comment to be deleted.
                    type: integer
                    example: 2
                required:
                - comment_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing task_id or comment_id.
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: Either task_id or comment_id is required
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 400
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
        '403':
          description: Forbidden, author mismatch.
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: You are not the author of this
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 403
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
        '404':
          description: Task or comment not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: Task not found
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 404
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
  /surveys/{survey}/tasks/{task_id}:
    get:
      operationId: getSurveyTask
      summary: Get survey task
      description: Get a specific task for a survey.
      tags:
      - Survey Tasks
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: task_id
        in: path
        description: The ID of the task to retrieve.
        required: true
        schema:
          type: integer
          example: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/surveyTask'
              example:
                status: incomplete
                description: '<p>Task 1: Delete r2</p>'
                task_id: 1
                comments:
                - created_on: '2022-03-08T22:23:06Z'
                  comment_id: 1
                  email: user2@example.com
                  description: <p>Comment for Task 1</p>
                label: q1
                created_on: '2022-03-08T22:35:42Z'
                path: selfserve/1a/123456
                email: user1@example.com
                orphaned: false
        '404':
          description: Task ID not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: No task found with id 686
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 404
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
    put:
      operationId: updateSurveyTask
      summary: Update survey task
      description: Update the status or element label of a survey task.
      tags:
      - Survey Tasks
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: task_id
        in: path
        description: The ID of the task to be updated.
        required: true
        schema:
          type: integer
          example: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - incomplete
                  - completed
                  - confirmed
                  description: New status of the task.
                  example: completed
                element_label:
                  type: string
                  description: 'New label of the question or comment element the task should be reassigned to.

                    '
                  example: q2
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/surveyTask'
              example:
                status: completed
                description: '<p>Task 1: Delete r2</p>'
                task_id: 1
                comments:
                - created_on: '2022-03-08T22:23:06Z'
                  comment_id: 1
                  email: user2@example.com
                  description: <p>Comment for Task 1</p>
                label: q2
                created_on: '2022-03-08T22:35:42Z'
                path: selfserve/1a/123456
                email: user1@example.com
                orphaned: false
        '400':
          description: Invalid/missing status or element label.
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: No status or element were specified
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 400
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
        '404':
          description: Task ID or element not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: Element does not exist in this survey
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 404
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
  /surveys/{survey}/tasks/{task_id}/comment:
    post:
      operationId: createSurveyTaskComment
      summary: Create survey task comment
      description: Create a comment for a survey task.
      tags:
      - Survey Tasks
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: task_id
        in: path
        description: 'The ID of the task to which the comment should be added.

          '
        required: true
        schema:
          type: integer
          example: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: 'Description of the comment in plain text or HTML format.

                    '
                  example: <p>Comment description</p>
              required:
              - description
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/surveyTask'
              example:
                status: incomplete
                description: '<p>Task 1: Delete r2</p>'
                task_id: 1
                comments:
                - created_on: '2022-03-08T22:23:06Z'
                  comment_id: 1
                  email: user2@example.com
                  description: <p>Comment for Task 1</p>
                label: q1
                created_on: '2022-03-08T22:35:42Z'
                path: selfserve/1a/123456
                email: user1@example.com
                orphaned: false
        '400':
          description: Empty/missing description
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: Description must not be empty
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 400
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
  /surveys/{survey}/tasks/reassign:
    put:
      operationId: updateSurveyTaskReassignLabel
      summary: Reassign survey task
      description: Reassign a survey task to a different element label.
      tags:
      - Survey Tasks
      parameters:
      - $ref: '#/components/parameters/survey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                element_label:
                  type: string
                  description: 'The label of the question or comment element whose tasks should be reassigned.

                    '
                  example: q1
                new_label:
                  type: string
                  description: 'New label of the question or comment element tasks should be reassigned to.

                    '
                  example: q2
              required:
              - element_label
              - new_label
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/surveyTask'
              example:
              - status: incomplete
                description: '<p>Task 1: Delete r2</p>'
                task_id: 1
                comments:
                - created_on: '2022-03-08T22:23:06Z'
                  comment_id: 1
                  email: user2@example.com
                  description: <p>Comment for Task 1</p>
                label: q2
                created_on: '2022-03-08T22:35:42Z'
                path: selfserve/1a/123456
                email: user1@example.com
                orphaned: false
              - status: completed
                description: '<p>Task 2: Change q2</p>'
                task_id: 2
                comments:
                - created_on: '2022-03-08T22:23:06Z'
                  comment_id: 1
                  email: user3@example.com
                  description: <p>First comment for Task 2</p>
                - created_on: '2022-03-08T22:23:06Z'
                  comment_id: 2
                  email: user1@example.com
                  description: <p>Second comment for Task 2</p>
                label: q2
                created_on: '2022-03-08T22:35:42Z'
                path: selfserve/1a/123456
                email: user2@example.com
                orphaned: false
        '400':
          description: Invalid/missing new or current element label.
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    description: A description of the error.
                    type: string
                    example: missing argument 'new_label'
                  $code:
                    description: The HTTP error code.
                    type: integer
                    example: 400
                  extra:
                    description: Extra information about the error.
                    type: string
                    example: null
components:
  parameters:
    survey:
      name: survey
      in: path
      required: true
      description: The survey path.
      example: selfserve/1a/123456
      schema:
        type: string
        format: uri
  schemas:
    surveyTask:
      type: object
      properties:
        status:
          type: string
          enum:
          - incomplete
          - completed
          - confirmed
          description: Status of the task.
          example: incomplete
        description:
          type: string
          format: html
          description: Description of the task in HTML format.
          example: <p>Task description</p>
        task_id:
          type: integer
          example: 1
          description: ID of the task.
        comments:
          type: array
          description: List of comments for the task.
          items:
            type: object
            properties:
              created_on:
                type: string
                format: timestamp
                example: '2022-03-08T22:23:06Z'
                description: Date and time the comment was created.
              comment_id:
                type: integer
                example: 1
                description: ID of the comment.
              email:
                type: string
                format: email
                example: user@example.com
                description: Email of the user who created the comment.
              description:
                type: string
                format: html
                example: <p>Task comment</p>
                description: Comment description in HTML format.
        label:
          type: string
          example: q1
          description: Label of the question or comment element (Descriptive Content).
        created_on:
          type: string
          format: timestamp
          example: '2022-03-08T22:35:42Z'
          description: Date and time the task was created.
        path:
          type: string
          example: selfserve/1a/123456
          description: Path to the survey.
        email:
          type: string
          format: email
          example: user2@example.com
          description: Email of the user who created the task.
        orphaned:
          type: boolean
          example: false
          description: "Whether the task is related to a question or comment element label that \nno longer exists.\n"
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: x-apikey
      description: 'In order to access the api, you''ll need to generate an API key. Refer to the

        instructions [here](/docs/decipher/api#section/API-Keys) to generate and

        configure an API key with the appropriate permission sets. You can generate

        as many keys as required.


        Configure each request to include your API key in the request header. For example:


        ```

        x-apikey: dp48ss3mgsaucyjtybxw728h7s4cgnwzhejtszdwhf4xpe8yhmtdwpk2ntdhtwbs

        ```

        '
x-tagGroups:
- name: Autoclose
  tags:
  - Autoclose
- name: Data Input and Output
  tags:
  - Data
  - Data Feed
  - Response Summary
  - Modifying Data
  - Datasources
  - Datasources Data
  - Umerge
- name: Survey Metadata
  tags:
  - Simulated Data
  - Survey State
  - Survey Evaluate
  - Survey Quotas
  - Survey Files
  - Survey Warnings
  - Survey Terms
  - Survey Subscribers
  - Survey Users
  - Survey Tasks
- name: Panels
  tags:
  - Panel Data
  - Panel Datapoints
  - Survey Panels
- name: Research Hub
  tags:
  - Users
  - Companies
  - Categories
  - Surveys
  - Panels
  - Crosstabs
  - Archives
  - Archival Reports
  - API Keys
  - Usage
  - Warnings Summary
- name: Crosstabs
  tags:
  - Crosstabs Configuration
  - Crosstabs Execution
  - Crosstabs Nets
  - Saved Crosstabs
  - Crosstabs Table Settings
  - Crosstabs Validation
  - Crosstabs Rim Weighting
- name: Dashboards
  tags:
  - Dashboards
- name: DQ APIs
  tags:
  - DQ-Specific API Calls
  - MaxDiff API Calls
  - Discrete Choice Model API Calls
  - Media Testimonial API Calls
- name: Response Summary
  tags:
  - Share Link
- name: Sample Management
  tags:
  - Bounced Emails
  - Participant Sources
- name: Distribution
  tags:
  - Email Distribution
  - SFTP Distribution
  - Slack Distribution
- name: Campaign Manager
  tags:
  - Campaigns
  - Campaign Email Invites
  - Campaign Exports
  - Campaign Lists
  - Shared Campaign Lists
  - Campaign Sends
  - Campaign Status Lists
  - Supression Lists
- name: Question Library
  tags:
  - Company Element
  - Company Elements
  - Survey Elements
  - Survey Element Report Settings
- name: Language Manager
  tags:
  - LM Application Data
  - LM Application Translations
  - Translation Resources
  - Translations
  - Translation Deltas
  - Translation Reservations
  - Primary Survey Language
  - Other Survey Languages
  - Unused Survey Languages
- name: Project Parameters
  tags:
  - Available Project Parameters
  - Saved Project Parameters
  - Project Parameters Configuration
- name: Multi-User Editing
  tags:
  - Available Sections
  - Check Out Section
  - Check In Section
  - Sync Section
  - Section Editor
  - Abandon Section
  - Validate Section
- name: Video Management
  tags:
  - Videos
  - Watermarked Videos
- name: Miscellaneous
  tags:
  - System Information
  - Logic Nodes
  - Logic Events
  - CATI
  - Global Search
  - Miscellaneous