openapi: 3.2.0
info:
  title: Decipher Rest Discrete Choice Model API Calls 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: Discrete Choice Model API Calls
paths:
  /surveys/{survey}/conjoint/status:
    get:
      operationId: getSurveyConjointStatus
      summary: Get survey conjoint statuses
      description: Retrieves a list of statuses for all Discrete Choice Model questions in a survey
      tags:
      - Discrete Choice Model API Calls
      parameters:
      - $ref: '#/components/parameters/survey'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    question_label:
                      type: string
                      description: The question label for the DCM question
                      example: q1
                    design_filename:
                      type: string
                      description: The filename of the design file
                      example: q1_design_abcd.dat
                    design_status:
                      type: string
                      description: 'Status for the creation of the design file,  one of `in_progress`, `completed`, or `failed: <message>`'
                      example: completed
                    design_timestamp:
                      type: string
                      description: Timestamp of the latest design status
                      example: '2025-02-10T21:14:50Z'
                    report_status:
                      type: string
                      description: 'Status for the creation of the report files, one of `in_progress`, `completed`, or `failed: <message>`'
                      example: in_progress
                    report_timestamp:
                      type: string
                      description: Timestamp of the latest report status
                      example: '2025-02-10T22:10:37Z'
  /surveys/{survey}/conjoint/report/{question_label}:
    get:
      operationId: getSurveyConjointReport
      summary: Get survey conjoint utilities
      description: Retrieves a utilities report for a specific Discrete Choice Model question in a survey. Utilities report must have already been run for this question.
      tags:
      - Discrete Choice Model API Calls
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: question_label
        in: path
        required: true
        schema:
          type: string
        description: The question label for the DCM question
      - name: data
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - raw_utilities
            - zeroed_utilities
            - utility_ranges
            - importance_ratios
            - importances
            - preferences
            - zc_diffs
        description: List of data types to include in the report
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    attribute_name:
                      type: string
                      description: The name of the attribute
                      example: Brand
                    aggregate_data:
                      type: object
                      properties:
                        importance:
                          type: string
                          description: The importance of the attribute
                          example: '0.12417560023'
                    respondent_data:
                      type: array
                      items:
                        type: object
                        properties:
                          utility_range:
                            type: string
                            description: The utility range for the respondent
                            example: '0.70357261395'
                          importance_ratio:
                            type: string
                            description: The importance ratio for the respondent
                            example: '0.11114124767'
                          respondent_id:
                            type: string
                            description: The identifier for the respondent
                            example: jwy3kwppp4yuqg86
                    levels:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            description: The name of the level
                            example: Decipher
                          aggregate_data:
                            type: object
                            properties:
                              preference:
                                type: string
                                description: The preference for the level
                                example: '0.01928257183'
                          respondent_data:
                            type: array
                            items:
                              type: object
                              properties:
                                raw_utility:
                                  type: string
                                  description: The raw utility for the respondent
                                  example: '0.42836917022'
                                zeroed_utility:
                                  type: string
                                  description: The zeroed utility for the respondent
                                  example: '0.0'
                                respondent_id:
                                  type: string
                                  description: The identifier for the respondent
                                  example: jwy3kwppp4yuqg86
                                zc_diff:
                                  type: string
                                  description: The zero-centered difference for the respondent
                                  example: '54.13455054824'
        '404':
          description: Not Found
        '409':
          description: Conflict
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