Forsta Data Feed API

openapi: 3.2.0
info:
  title: Decipher Rest Data Feed 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: Data Feed
  description: 'Get data from multiple live surveys using a single API endpoint

    (optionally restrict by date and survey paths).'
paths:
  /datafeed/{feed}:
    get:
      operationId: getDatafeed
      summary: Get new data
      description: 'Every live or closed survey accessible to this account will be considered for the feed. This list can be filtered by

        the `paths` argument. Once a complete list of surveys has been generated, participants with data update time greater

        than the last time the feed was ran are retrieved. If `start` is supplied, then the participant is further filtered.


        By default `cond` is set to `qualified` retrieving only qualified participants. You can specify `ALL` for all participants

        including partials or other conditions known, to Crosstabs. Invalid conditions will be returned as errors but will not

        prevent other surveys'' data from being generated.


        **Pagination**: This call will return 10,000 participants at a time. If more would be generated, `complete` will be set to false

        in the returned record and you should call this function again to get more data. A complete feed means that at the time

        of each survey being processed, no more data was available.


        **Data format**: The data returned uses the JSON data format, using the default variable layout.


        **Acknowledgement**: If you set `autoAck` to true, the data is automatically advanced. If not, every time you receive

        data and after you successfully process it you must make the /ack call as documented below with the ack value you received.

        Otherwise the feed is not advanced and you will receive the data again. Note there is no guarantee that you receive

        exactly the same response as in the last call as new surveys or participants may have appeared. However the data you were

        sent is guaranteed to be sent again.


        **When to use ACK**: If you do not use the ACK system, Decipher advances the feed state as soon as the entire request was

        completed -- even if the network connection is reset before you have received the entire reply, or if an error is generated while

        you are processing the data. We only recommend `autoAck` for testing purposes.


        **Partial data**: If you supply `ALL` as `cond` rather than the default `qualified` then partial data is also included. The

        same participant record may appear multiple times: once each time his partial data is updated and once if they complete.


        **Data edits**: a data edit that modifies participant data does NOT resend the data.


        **New surveys**: The list of surveys to include in the feed is considered on every request. As new surveys go live or are

        closed they will be added to the feed. Set `paths` to a specific subset of the surveys you want if you want consider only

        those. This will filter the list of live and closed surveys to include only those specified. This must be repeated for

        every request.


        The response is an object containing these fields:

        * `complete`: if true, this response is all the data available. If false, more data exists and you should continue to ask for the data feed to get more data immediately. By default, no more than 10,000 records will be sent at a time.

        * `ack`: this UUID describes this particular response value; the feed will move forward only if the caller acknowledges receipt in the next call (see below).

        * `results`: an array of participant records. Each participant record contains:

        * variables from the default layout as per JSON data record

        * `$survey` set to the path of the survey'
      tags:
      - Data Feed
      parameters:
      - $ref: '#/components/parameters/feed'
      - name: start
        in: query
        description: 'ISO-8601 date with the minimum completion time to retrieve.

          Record before this date will not be considered.

          This parameter should be passed with the same value

          every time until data has been exhausted. Thus it should

          only be used if somehow data received is lost and needs

          to be re-synchronized.

          '
        schema:
          type: string
          format: date-time
      - name: format
        in: query
        description: 'Normally not used. Use json_panel as value to synchronize

          data with a participant panel (this feature is enabled

          only for certain clients)

          '
        schema:
          type: string
          default: json
      - name: autoAck
        in: query
        description: 'If set to true, no ack call is required to move

          the feed forward.

          '
        schema:
          type: boolean
          default: false
      - name: states
        in: query
        description: 'List of survey states to accept data from. By default

          only live and closed surveys are scanned for data but

          through this parameter you may include surveys in dev or

          testing mode.

          '
        schema:
          type: array
          default:
          - live
          - closed
          items:
            type: string
            enum:
            - live
            - closed
            - testing
            - dev
      - name: paths
        in: query
        description: 'If specified, return only the data from the list of survey

          paths provided that you have permission to view.

          '
        example:
        - selfserve/xyz/123456
        schema:
          type: array
          items:
            type: string
      - name: fields
        in: query
        description: 'Extract only these variables from all the surveys.

          '
        schema:
          type: array
          items:
            type: string
      - name: cond
        in: query
        description: 'By default only qualified participants are fetched. Specify

          ALL for all data or another condition (which must be

          applicable to ALL your surveys)

          '
        schema:
          type: string
          default: qualified
          enum:
          - all
          - qualified
      - name: limit
        in: query
        description: 'Limit the number of results returned per request.

          '
        schema:
          type: integer
          default: 10000
      - name: surveyLabels
        in: query
        description: 'If survey labels should be part of the request.

          '
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    ack:
                      type: string
                      format: uuid
                      description: 'This UUID describes this particular response value.

                        The feed will move forward only if the caller acknowledges

                        receipt in the next call.

                        '
                    errors:
                      type: object
                    results:
                      type: array
                      description: 'An array of participant records.

                        '
                      items:
                        type: object
                        properties:
                          status:
                            description: The survey completion status.
                            example: 1
                            type: integer
                          uuid:
                            type: string
                            format: uuid
                            description: The survey `uuid`.
                            example: jwy3kwppp4yuqg86
                          returl:
                            type: string
                            format: url
                            example: https://azkaban.decipherinc.com/survey/selfserve/53b/191004?state=c8ed2b43-8525-4aed-9651-6460940d411e
                          vmobiledevice:
                            type: integer
                            description: The respondent's mobile device code.
                            example: 5
                          url:
                            type: string
                            description: The survey builder url.
                            example: http://release.decipherinc.com/survey/selfserve/1a/123456
                          $survey:
                            type: string
                            description: The survey path.
                            example: selfserve/53b/191005
                          vbrowser:
                            type: integer
                            description: The respondent's browser code.
                            example: 11
                          qtime:
                            type: number
                            format: float
                            description: The elapsed time (seconds) from survey start to complete.
                            example: 56.235
                          list:
                            type: integer
                            example: 0
                          dcua:
                            type: string
                            example: ..
                          markers:
                            type: string
                            example: qualified,/totalQuota/Total
                          record:
                            type: integer
                            example: 1
                          session:
                            type: string
                            format: uuid
                            description: Unique user session ID.
                            example: cwsps4gewqc0p175
                          vos:
                            type: integer
                            description: The respondent's operating system (os).
                            example: 13
                          date:
                            type: string
                            example: 09/02/2020 14:52
                          vlist:
                            type: integer
                            example: 1
                          userAgent:
                            type: string
                            example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:69.0) Gecko/20100101 Firefox/69.0
                          vmobileos:
                            type: integer
                            example: 6
                          start_date:
                            type: integer
                            example: 10/17/2019 15:09
                          q1:
                            description: An example question response
                            example: '8'
                            type: string
                          q2a:
                            description: An example question response
                            example: I thought it was great.
                            type: string
                          q2b:
                            description: An example question response
                            example: I thought it was not so great.
                            type: string
                    complete:
                      type: boolean
                      description: 'If true, this response is all the data available. If false,

                        more data exists and you should continue to ask for the

                        data feed to get more data immediately. By default, no more

                        than 10,000 records will be sent at a time.

                        '
      x-codeSamples:
      - lang: Curl
        source: 'curl -H x-apikey: {api_key} -X GET {server}/api/v1/datafeed/myFeed

          '
      - lang: Cli
        source: 'beacon get datafeed/myFeed > myfile.json

          '
    put:
      operationId: updateDatafeed
      summary: Update feed
      description: 'Updates the internal feed state. Call the Feed state GET method below

        to get the current state. You can then e.g. copy it over to another name.'
      tags:
      - Data Feed
      parameters:
      - $ref: '#/components/parameters/feed'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  type: string
                  description: A state previously retrieved using `datafeed/{feed}/state`
              required:
              - state
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
      x-codeSamples:
      - lang: Curl
        source: 'curl -H x-apikey: {api_key} -X PUT {server}/api/v1/datafeed/myNewFeed?state=0a66d78d-46cd-47fb-a1f7-e6d779e6b7c6

          '
      - lang: Cli
        source: 'beacon PUT datafeed/myFeed state=0a66d78d-46cd-47fb-a1f7-e6d779e6b7c6

          '
    delete:
      operationId: deleteDatafeed
      summary: Reset feed
      description: 'Clears the state of the feed. The next `GET` request will receive data

        from the beginning.'
      tags:
      - Data Feed
      parameters:
      - $ref: '#/components/parameters/feed'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
      x-codeSamples:
      - lang: Curl
        source: 'curl -H x-apikey: {api_key} -X DELETE {server}/api/v1/datafeed/myFeed

          '
      - lang: Cli
        source: 'beacon delete datafeed/myFeed

          '
  /datafeed/{feed}/state:
    get:
      operationId: getDatafeedState
      summary: Get feed state
      description: 'Returns the stored internal state for this feed. This is mainly for troubleshooting processes. An object with a single key, state, its value an object mapping survey path to a list of two items:

        - 0: minimum timestamp for data retrieval - 1: an array of UUIDs of records retrieved

        The list of UUIDs is only set if data was partially retrieved during a POST due of exceeding the 10,000 element limit. Once a survey’s data has been completely returned up until a timestamp, this list is cleared.'
      tags:
      - Data Feed
      parameters:
      - $ref: '#/components/parameters/feed'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    ack:
                      type: string
                      format: uuid
                      description: 'This UUID describes this particular response value.

                        The feed will move forward only if the caller acknowledges

                        receipt in the next call.

                        '
                    current:
                      type: object
                    pending:
                      type: object
      x-codeSamples:
      - lang: Curl
        source: 'curl -H x-apikey: {api_key} -X GET {server}/api/v1/datafeed/myFeed/state

          '
      - lang: Cli
        source: 'beacon get datafeed/myFeed/state

          '
  /datafeed/{feed}/ack:
    post:
      operationId: createDatafeedAck
      summary: Acknowledge feed
      description: Call this method to move the data feed forward.
      tags:
      - Data Feed
      parameters:
      - $ref: '#/components/parameters/feed'
      - name: ack
        in: query
        required: true
        description: 'The `ack` value you received from calling `GET`.

          '
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ack_valid:
                    type: boolean
      x-codeSamples:
      - lang: Curl
        source: 'curl -H x-apikey: {api_key} -X GET {server}/api/v1/datafeed/myFeed/ack?ack=0a66d78d-46cd-47fb-a1f7-e6d779e6b7c6

          '
      - lang: Cli
        source: 'beacon get datafeed/myFeed/ack ack=0a66d78d-46cd-47fb-a1f7-e6d779e6b7c6

          '
components:
  parameters:
    feed:
      name: feed
      in: path
      required: true
      description: 'Any unique ID that will identify the feed. Feeds are namespaced

        per user, so your `all` feed is unique to you.

        '
      schema:
        type: string
  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