Forsta Session API

openapi: 3.2.0
info:
  title: Integration Session API
  version: ''
servers:
- url: https://{server}
  description: Replace server with your instance domain.
  variables:
    server:
      default: staging.panel.dev.focusvision.com/
      description: Server domain
tags:
- name: Session
paths:
  /api.pro#method=integration.session.get:
    post:
      operationId: getSessionGet
      summary: Get session info using the sessionkey
      description: 'Get session info using the sessionkey. The return values contain basic data about the session,

        including project ID, campaign ID, panelist ID, status, start time etc.'
      tags:
      - Session
      security:
      - ApiKey: []
      parameters:
      - $ref: '#/components/parameters/method'
        schema:
          enum:
          - integration.session.get
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sesKey
              - sesString
              properties:
                sesKey:
                  description: A valid login hash.
                  type: string
                  example: 5a15852c564933807bbd36da58071063
                sesString:
                  description: 16 character panelist session string from the URL
                  type: string
                  example: e0197525e7129c5c
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/error'
                - type: object
                  properties:
                    success:
                      example: true
                      type: boolean
                    data:
                      example:
                        projectid: 23
                        campaignid: 59
                        panelistid: 34359
                        status: started
                        starttime: '2013-01-01 23:59:59'
                      type: object
                      properties:
                        projectid:
                          type: integer
                        campaignid:
                          type: integer
                        panelistid:
                          type: integer
                        status:
                          type: string
                        starttime:
                          type: string
              examples:
                success:
                  summary: Success
                  value:
                    success: true
                    data:
                      projectid: 23
                      campaignid: 59
                      panelistid: 34359
                      status: started
                      starttime: '2013-01-01 23:59:59'
                error-0:
                  description: Session with supplied session string is not found.
                  summary: Session string invalid
                  value:
                    success: false
                    error: Session key (sesskey) is not valid
                    errno: '20202'
                error-1:
                  description: Session has expired.
                  summary: Session expired
                  value:
                    success: false
                    error: Session has expired. You must start a new session.
                    errno: '30100'
                error-2:
                  description: Session is not found for supplied session key.
                  summary: Session not found
                  value:
                    success: false
                    error: sessionkey not found
                    errno: '30200'
                error-3:
                  description: User ID not found for supplied session key.
                  summary: Session not found
                  value:
                    success: false
                    error: userid for sessionkey not found
                    errno: '30200'
                error-4:
                  description: Session key is not in correct format.
                  summary: Session invalid
                  value:
                    success: false
                    error: sessionkey is invalid
                    errno: '30300'
  /api.pro#method=integration.session.update:
    post:
      operationId: getSessionUpdate
      summary: Update the session status using the sessionkey
      description: 'Update the session status using the sessionkey. Optionally reward points can be distributed.

        Distributed points will also link the points to the panelist session. Note: Specified reward points will override

        any other default point values in the campaign manager.'
      tags:
      - Session
      security:
      - ApiKey: []
      parameters:
      - $ref: '#/components/parameters/method'
        schema:
          enum:
          - integration.session.update
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sesKey
              - sesString
              - status
              properties:
                sesKey:
                  description: A valid login hash.
                  type: string
                  example: 5a15852c564933807bbd36da58071063
                sesString:
                  description: 16 character panelist session string from the URL
                  type: string
                  example: e0197525e7129c5c
                status:
                  description: Set the status of the completing panelist.
                  type: string
                  enum:
                  - profile
                  - quota
                  - started
                  - completed
                  example: profile
                points:
                  description: Optional to supply custom number of points
                  type: integer
                  example: 50
                note:
                  description: Optional to supply custom reward points activity note; note is only saved if a non-zero points value is provided or the campaign is set up to issue points for the status that is provided.
                  type: string
                  example: Completed survey
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/error'
                - type: object
                  properties:
                    success:
                      type: boolean
              examples:
                success:
                  summary: Success
                  value:
                    success: true
                error-0:
                  description: Session with supplied session string is not found.
                  summary: Session string invalid
                  value:
                    success: false
                    error: Session key (sesskey) is not valid
                    errno: '20202'
                error-1:
                  description: The project is closed and status cannot be updated.
                  summary: Project Closed
                  value:
                    success: false
                    error: Project is closed
                    errno: '20203'
                error-2:
                  description: The campaign is expired and status cannot be updated.
                  summary: Campaign Expired
                  value:
                    success: false
                    error: Campaign is expired
                    errno: '20203'
                error-3:
                  description: The panelist is opted out.
                  summary: Panelist Opted Out
                  value:
                    success: false
                    error: Panelist opted out
                    errno: '20203'
                error-4:
                  description: 'The supplied status is invalid. The status must be one of the following: "profile", "quota" or "completed".'
                  summary: Status invalid
                  value:
                    success: false
                    error: Status (status) is unknown
                    errno: '20203'
                error-5:
                  description: The supplied status in valid. The panelist must have a started status before changing it to this status.
                  summary: Status invalid
                  value:
                    success: false
                    error: 'Somebody is trying to go from status: ‘(current panelist status)’ to ‘(status)’ while bypassing ''started’'
                    errno: '20203'
                error-6:
                  description: The supplied status is invalid for panelist.
                  summary: Status invalid
                  value:
                    success: false
                    error: Status can only be set higher than its current value of ‘(current panelist status)’
                    errno: '20203'
                error-7:
                  description: The supplied status is invalid. The panelist is pending and their status can be changed to invited only.
                  summary: Status invalid
                  value:
                    success: false
                    error: A pending session can only be changed to 'invited'
                    errno: '20203'
                error-8:
                  description: The panelist exit status is already recorded. Their status cannot be changed.
                  summary: Status invalid
                  value:
                    success: false
                    error: Exit status already recorded
                    errno: '20203'
                error-9:
                  description: The supplied points value must be positive.
                  summary: Points invalid
                  value:
                    success: false
                    error: Points value must be positive
                    errno: '20204'
                error-10:
                  description: Session has expired.
                  summary: Session expired
                  value:
                    success: false
                    error: Session has expired. You must start a new session.
                    errno: '30100'
                error-11:
                  description: Session is not found for supplied session key.
                  summary: Session not found
                  value:
                    success: false
                    error: sessionkey not found
                    errno: '30200'
                error-12:
                  description: User ID not found for supplied session key.
                  summary: Session not found
                  value:
                    success: false
                    error: userid for sessionkey not found
                    errno: '30200'
                error-13:
                  description: Session key is not in correct format.
                  summary: Session invalid
                  value:
                    success: false
                    error: sessionkey is invalid
                    errno: '30300'
components:
  schemas:
    error:
      type: object
      properties:
        success:
          type: boolean
        error:
          description: The error message.
          type: string
        errno:
          description: The error code.
          type: string
  parameters:
    method:
      name: method
      in: query
      required: true
      description: Method
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    ApiKey:
      type: apiKey
      in: query
      name: sesKey
x-tagGroups:
- name: Data Input and Output
  tags:
  - Auth
  - Campaign
  - Category
  - Community
  - Datapoint
  - Panel
  - Notes
  - Panelist
  - Project
  - Reminder
  - Sample
  - Session
  - Survey
  - Token