Forsta Companies API

openapi: 3.2.0
info:
  title: Decipher Rest Companies 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: Companies
paths:
  /rh/companies:
    get:
      operationId: getRHCompanies
      summary: List companies
      description: 'What companies exist on the system? Returns an array of company objects.

        Supervisor access required.'
      tags:
      - Companies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    max_invalid_attempts:
                      type: integer
                    is_supercompany:
                      type: boolean
                    allow_shared_accounts:
                      type: boolean
                    product_builder:
                      type: string
                      format: ISO-8601 timestamp with timezone
                    id:
                      type: integer
                    updated_by:
                      type: integer
                    product_offline:
                      type: string
                      format: ISO-8601 timestamp with timezone
                    min_classes:
                      type: integer
                    created_by:
                      type: integer
                      description: ID of the user that created this company
                    supercompany:
                      type: integer
                    product_dashboard:
                      type: string
                      format: ISO-8601 timestamp with timezone
                    expires_on:
                      type: string
                      format: ISO-8601 timestamp with timezone
                    subdirectories:
                      type: array
                    description:
                      type: string
                    inactivity_timeout:
                      type: integer
                    product_content_editor:
                      type: string
                      format: ISO-8601 timestamp with timezone
                    name:
                      type: string
                    password_expire_days:
                      type: integer
                    created_on:
                      type: string
                      format: ISO-8601 timestamp with timezone
                    product_campaign:
                      type: string
                      format: ISO-8601 timestamp with timezone
                    min_password_len:
                      type: integer
                    updated_on:
                      type: string
                      format: ISO-8601 timestamp with timezone
              example:
              - max_invalid_attempts: 6
                is_supercompany: false
                allow_shared_accounts: false
                product_builder: null
                id: 1
                updated_by: null
                product_offline: null
                min_classes: 2
                created_by: 215
                supercompany: null
                product_dashboard: null
                expires_on: '2021-01-08T01:29:49Z'
                subdirectories: []
                description: string
                inactivity_timeout: 86400
                product_content_editor: null
                name: Example Inc.
                password_expire_days: null
                created_on: '2021-01-01T01:29:49Z'
                product_campaign: null
                min_password_len: 7
                updated_on: '2021-01-02T01:29:49Z'
  /rh/companies/{company}/preferences:
    get:
      operationId: getRHCompanyPreferences
      summary: List company preferences
      description: Retrieves all preferences for a specific company.
      parameters:
      - $ref: '#/components/parameters/company'
      tags:
      - Companies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value:
                    appliedDefaults:
                    - fwu
                    fwu: compat
  /rh/companies/{company}/preferences/{key}:
    put:
      operationId: updateRHCompanyPreferencesKey
      summary: Update company preference
      description: Set a preference to a new value.
      tags:
      - Companies
      parameters:
      - name: company
        description: company to update the preference for
        in: path
        required: true
        schema:
          type: string
        example: 1
      - name: key
        description: the preference to update
        in: path
        required: true
        schema:
          type: string
        example: fwu
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  description: the new value
                  type: string
              required:
              - value
            example:
              value: both
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /rh/companies/{company}/preferences/{key}/history:
    get:
      operationId: getRHCompanyPreferenceHistory
      summary: Get preference history
      description: 'View a list of all changes to a specific preference. Returns

        an array of history entries.'
      tags:
      - Companies
      parameters:
      - name: company
        description: company ID or name
        in: path
        required: true
        schema:
          type: string
        example: 1
      - name: key
        description: name of preference
        in: path
        required: true
        schema:
          type: string
        example: fwu
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    new:
                      description: the value of the preference
                    previous:
                      description: the previous value of the preference
                    user_id:
                      type: integer
                      description: id of the account responsible for the change
                    tstamp:
                      type: string
                      format: ISO 8601 timestamp with timezone
                      description: time of change
              example:
              - new: compat
                previous: unicode
                tstamp: '2014-10-21T14:27:38Z'
                user_id: 104
              - new: unicode
                previous: compat
                tstamp: '2014-10-21T14:20:51Z'
                user_id: 104
              - new: compat
                previous: null
                tstamp: '2014-10-21T14:20:35Z'
                user_id: 104
  /rh/companies/{company}/groups:
    get:
      operationId: getRHCompaniesGroups
      summary: List groups within a company
      description: List all user groups within a company. Edit company access required.
      parameters:
      - name: company
        description: 'can be "all" for all companies, "self" for the company of the currently

          logged in user, a numeric company ID, or company name

          '
        in: path
        required: true
        schema:
          type: string
      tags:
      - Companies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    company_id:
                      type: integer
                      description: ID of the company to whom this group belongs
                    company_name:
                      type: string
                      description: Company name
                    default_permissions:
                      type: string
                      description: Default permissions for all users in group
                    name:
                      type: string
                      description: Group name
                    id:
                      type: integer
                      description: Group id
                    users:
                      type: array
                      description: List of user objects
                      items:
                        type: object
                        properties:
                          last_login_where:
                            type: string
                            format: ip address
                          supervisor:
                            type: boolean
                          subdirectory:
                            type: string
                          type:
                            type: string
                          company:
                            type: integer
                          id:
                            type: integer
                          last_password_change:
                            type: string
                            format: ISO-8601 timestamp with timezone
                          last_login:
                            type: string
                            format: ISO-8601 timestamp with timezone
                          active:
                            type: boolean
                          fullname:
                            type: string
                          lockedout_until:
                            type: string
                            format: ISO-8601 timestamp with timezone
                          login:
                            type: string
                            format: email
                            description: Email or name if no email is specified
                          expires_on:
                            type: string
                            format: ISO-8601 timestamp with timezone
                          staff:
                            type: boolean
                          added_to_group_by_email:
                            type: string
                            format: email
                            description: Email of the user who added this user to the group
                          added_to_group_on:
                            type: string
                            format: ISO-8601 timestamp with timezone
                            description: Date on which this user was added to the group
  /rh/companies/{company}/retention:
    get:
      operationId: getRHCompanyRetention
      summary: Get company data retention settings
      description: Retrieves all data retention settings for a company.
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/company'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  archive_days:
                    type: integer
                    description: Days before closed surveys are archived in this company.
                  clear_data_days:
                    type: integer
                    description: Days after a survey is archived until all respondent data in the archive is removed.
                  server_delete_days:
                    type: integer
                    description: The global default setting for archive_days that might apply to other companies.
                  server_archival_days:
                    type: integer
                    description: The global default setting for clear_data_days that might apply to other companies.
                  server_clear_data_days:
                    type: integer
                    description: Days after a survey has been archived until the archive has been permanently removed.
              example:
                archive_days: 20
                clear_data_days: null
                server_delete_days: 365
                server_archival_days: 20
                server_clear_data_days: null
components:
  parameters:
    company:
      name: company
      in: path
      required: true
      description: 'A company name, numeric company id, or "self" for your own company.

        '
      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