Forsta Survey State API

openapi: 3.2.0
info:
  title: Decipher Rest Survey State 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 State
paths:
  /surveys/{survey}/state/live:
    post:
      operationId: createSurveyStateLive
      summary: Launch survey
      description: 'Launches a survey. Goes through the launch process for a survey. If

        there are any warnings those will be returned and the survey will not be

        launched. Otherwise the surveys state will be changed to "live".

        Requires survey edit permission for the project.'
      tags:
      - Survey State
      parameters:
      - $ref: '#/components/parameters/survey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                relaunch:
                  description: This is required if a survey is in the closed state and needs to be set live.
                  default: false
                  type: boolean
                ignore_warnings:
                  description: 'This will ignore other survey warnings including: open tasks, incompatible elements, missing project parameters, and outdated translations.'
                  default: false
                  type: boolean
                ignore_kinesis:
                  description: This will ignore any kinesis errors when setting the survey live and will skip any syncing with kinesis.
                  default: false
                  type: boolean
                ignore_fulcrum:
                  description: This will ignore any fulcrum errors when setting the survey live and will skip syncing questions and changing the survey state on fulcrum.
                  default: false
                  type: boolean
                ignore_sst:
                  description: Passing this will ignore any sst warnings and launch the survey without valid progress data. Skipping this is not recommended and may result in uncaught survey errors and an inaccurate progress bar.
                  default: false
                  type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  info:
                    type: array
                    items:
                      type: string
                  warnings:
                    type: array
                    items:
                      type: object
                      properties:
                        imported:
                          type: array
                          items:
                            type: string
                        incompatible:
                          type: array
                          items:
                            type: string
                        offline:
                          type: array
                          items:
                            type: string
                        translations:
                          type: array
                          items:
                            type: string
                        tasks:
                          type: array
                          items:
                            type: string
                        kinesis:
                          type: array
                          items:
                            type: string
                        fulcrum:
                          type: array
                          items:
                            type: string
                        sst:
                          type: array
                          items:
                            type: string
                        project_parameters:
                          type: array
                          items:
                            type: string
  /surveys/{survey}/state/live/warnings:
    get:
      operationId: getSurveyStateLiveWarnings
      summary: Get launch warnings
      description: Returns any launch warnings that will appear when launching the survey.
      tags:
      - Survey State
      parameters:
      - $ref: '#/components/parameters/survey'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  imported:
                    type: array
                    items:
                      type: string
                  incompatible:
                    type: array
                    items:
                      type: string
                  offline:
                    type: array
                    items:
                      type: string
                  translations:
                    type: array
                    items:
                      type: string
                  tasks:
                    type: array
                    items:
                      type: string
                  kinesis:
                    type: array
                    items:
                      type: string
                  fulcrum:
                    type: array
                    items:
                      type: string
                  sst:
                    type: array
                    items:
                      type: string
                  project_parameters:
                    type: array
                    items:
                      type: string
  /surveys/{survey}/state/warnings:
    get:
      operationId: getSurveyStateWarnings
      summary: Get warnings
      description: 'Retrieve project warnings for a survey.


        Only events experienced by non-users (i.e., logged-out participants) in

        non-testing surveys are reported. Best efforts are made to eliminate duplicate

        events from the results.'
      tags:
      - Survey State
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: types
        description: restrict events returned to just these types
        in: query
        required: false
        schema:
          default:
          - blocks
          - missing_resources
          - exceptions
          - quota_misses
          type: array
      - name: start
        description: restrict events returned to just those occurring on/after this date (in ISO 8601 format)
        example: '2020-01-01'
        in: query
        required: false
        schema:
          type: string
      - name: end
        description: restrict warnings counts to just those occurring on/before this date
        example: '2020-12-31'
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: survey name
                  path:
                    type: string
                    description: survey path
                  company:
                    type: integer
                    description: company ID
                  events:
                    description: an array of events consisting of the following properties (subject to data retention rules)
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: string
                          format: timestamp
                          description: time of even occurrence or observation
                        type:
                          type: string
                          description: event type
                          enum:
                          - blocks
                          - missing_resources
                          - exceptions
                          - quota_misses
                        details:
                          type: object
                          description: an object consisting of properties that are specific to the event type
                  counts:
                    description: full event counts
  /surveys/{survey}/state/close:
    post:
      operationId: createSurveyStateClose
      summary: Close survey
      description: Closes a survey. The survey's state is modified from any other state to "closed" immediately, preventing new participants from starting the survey. Requires survey edit permission for the project.
      tags:
      - Survey State
      parameters:
      - $ref: '#/components/parameters/survey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                now:
                  type: boolean
                  description: by default participants have 1 hour from close time to finish a survey if they already started. Setting to `true` closes it immediately.
                  default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
components:
  parameters:
    survey:
      name: survey
      in: path
      required: true
      description: The survey path.
      example: selfserve/1a/123456
      schema:
        type: string
        format: uri
  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