Forsta Crosstabs Execution API

openapi: 3.2.0
info:
  title: Decipher Rest Crosstabs Execution 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: Crosstabs Execution
paths:
  /surveys/{survey}/crosstabs/execute:
    post:
      operationId: createSurveyCrosstabsExecute
      summary: Execute crosstabs
      description: 'Allows you to execute a crosstabs run with custom segments and filters. This

        is exactly the same interface that the crosstabs user interface uses to get

        the data to display the tables.


        The normal output is fairly complex: you may also request very

        simplified format by passing `simplified` set to `true`.


        If you specify `simplified` = true, the output is vastly simplified. It will

        be an object with one property by table label, for example `q1$r1`. The value

        is an array of the rows displayed: the first element is the row''s title and

        the next N*2 elements are the percentage or stat value and count, one per

        segment.'
      tags:
      - Crosstabs Execution
      parameters:
      - $ref: '#/components/parameters/survey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                simplified:
                  description: Generate vastly simplified output rather than the full
                  default: false
                  type: boolean
                segments:
                  description: "An array of segment objects to split all the tables by. Each\nsegment object should contain the properties `title`, `cond` and\nmay optionally contain `sg` to create custom stat test groups. If\nyou do not specify a `title`, one is attempted derived from\n`cond` (this is possible only for simple conditions like\n\"q1.r1\"). An optional `weight` will override any global weight: it \nshould be a condition resolving to a numeric variable like `nweight.val`.\n"
                  default:
                  - title: All
                    cond: ALL
                  type: array
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                      cond:
                        type: string
                      sg:
                        type: string
                      weight:
                        type: string
                    required:
                    - title
                    - cond
                filters:
                  description: 'An array of Python conditions to apply. These filter conditions

                    are applied before any segments.

                    '
                  default:
                  - qualified
                  type: array
                  items:
                    type: string
                base:
                  description: "How should percentages be calculated?\n\n+ `answering`: percentages are based on those answering the\n  question.\n+ `segment`: the total in the segment is used.\n+ `shown`: percentages shown but not necessarily answering the\n  question.\n+ `variable`: percentage shown for the variable (for checkbox\n  variables only; you must have `trackVars=\"checkbox\"` configured)"
                  default: answering
                  type: string
                  enum:
                  - answering
                  - segment
                  - shown
                  - variable
                tables:
                  description: Show only tables with these table labels.
                  type: array
                  items:
                    type: string
                aggregates:
                  description: 'Show output matching report grid tables. If set to `false`,

                    question tables are not aggregated and a separate table is shown

                    for each data variable. Not Applicable for saved reports.

                    '
                  default: true
                  type: boolean
                weight:
                  description: 'Apply weights to all calculations. Specify a condition which will

                    resolve to a weight, such as `nweight.val` for an uploaded weight schema.

                    Segments may override the global weight.

                    '
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  segments:
                    type: array
                    description: An array of the segment objects you requested.
                    items:
                      type: object
                      properties:
                        count:
                          type: integer
                          description: Count of participants matching the segment.
                        abbr:
                          type: string
                          description: Label used for stat testing.
                        sg:
                          type: string
                          description: 'If is set and not null, this segment was stat tested

                            against only other segments within the same `sg` value.

                            '
                        cond:
                          type: string
                          description: 'Segment condition (Python expression, e.g. "ALL" or

                            "q1.r1")

                            '
                        title:
                          type: string
                          description: Segment's title.
                  objects:
                    type: array
                    description: An array of the table data.
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                          description: 'The table label. This uniquely identifies a table. The

                            table label consists of the question''s system label (i.e.

                            label as specified in the XML file, and not through e.g.

                            variables.xls or data export customization), a $ sign then

                            a sub-label.  For example, if question q1 has only one

                            table it will be labelled `q1$`. Multiple tables might be

                            labelled `q1$r1` and `q1$mean` (for Mean Summary table).

                            '
                        qlabel:
                          type: string
                          description: The label of the underlying question.
                        title:
                          type: string
                          description: 'The main title of this table. This will be the question''s

                            title.

                            '
                        subtitle:
                          type: string
                          description: 'When a question has multiple tables, each will have a

                            different subtitle. May be null if no subtitle.

                            '
                        rows:
                          description: 'An array of objects defining the table row structures.

                            '
                          type: array
                          items:
                            type: object
                            properties:
                              obj:
                                type: string
                                description: 'The underlying object for the row (e.g. "q1,c1" would

                                  mean the row was created from the definition of

                                  column "c1" within question "q1").

                                  '
                              title:
                                type: string
                                description: 'The reporting title to be displayed for the row (the

                                  reporting title starts out as what is specified in

                                  the survey.xml with HTML etc. stripped; it can be

                                  customized in the report).

                                  '
                              label:
                                type: string
                                description: 'The row label. This is typically the label of the

                                  underlying row or column, e.g. "c1".

                                  '
                              cond:
                                type: string
                                description: 'The Python logic condition that was used to generate

                                  the data for the table row.

                                  '
                              dv:
                                type: integer
                                description: 'The data value used for statistical calculation (e.g.

                                  if showing a rating question table with 5 rows, the

                                  data values might span from 5 to 1 or 1 to 5

                                  depending on whether the scale is ascending or

                                  descending).

                                  '
                              intent:
                                type: string
                                enum:
                                - total
                                - data
                                - numnet
                                - net
                                - stat
                                description: 'Set to `total` for the total row, `data` for ordinary

                                  data rows showing a percentage, `numnet` for numeric

                                  nets, `net` for normal nets and `stat` for statistic

                                  rows.

                                  '
                              stat:
                                type: string
                                enum:
                                - counts
                                - mean
                                - stddev
                                - median
                                - se
                                - sum
                                description: 'If intent="stat", this describes what stat is being

                                  shown in this row. One of `counts` (checkbox count),

                                  `mean`, `stddev`, `median`, `se` (Standard Error) or

                                  `sum`.

                                  '
                              qa:
                                type: array
                                items:
                                  type: string
                                description: 'optional property: If it exists it''s an array of QA

                                  codes specific to the underlying survey row or

                                  column.

                                  '
                              pct:
                                type: string
                                description: 'Hint on how to display percentages. If `null` then

                                  percentages should not be disabled for this table

                                  row. This value is set on rows that are not included

                                  in the total base (I.e. "Refuse to Answer") which in

                                  the survey.xml are configured as `aggregates="0"`.

                                  '
                        data:
                          type: array
                          items:
                            type: array
                            items:
                              type: array
                              items:
                                type: number
                          description: "The `data` array contains one entry per item in the `rows`.\nEach entry in data is another array, containing one item\nper segment in this table. That final item is an array\nagain with two possible layouts. If the row's `intent` is\n`stat` then this is a statistical row with 3 items:\n\n* `0` the stat value (mean, median etc. depending on the\n  `stat` property of the matching row)\n* `1` the count of items matching the condition\n* `2` stat testing data (see below).\n\nIf `intent` is set to anything but `stat` the row is a\npercentage row, i.e. displaying a count and percentages.\nIt will have 5 items:\n\n* `0` vertical percentage, relative to the effective base\n  for this row. This percentage is emitted with 6 digits\n  of precision\n* `1` weighted count (rounded to nearest number)\n* `2` unweighted count. This will be the same as item #1\n  unless weighting was applied\n* `3` effective base. This is used for stat testing\n  calculations and will be slightly different from normal\n  base if weighting was used.\n* `4` stat testing data. Either `null` or an array\n  containing references to other columns where a stat test\n  was successful. The reference is either the upper or\n  lower-case variant of the row's `abbr` property.\n\nIf you specify `simplified` = true, the output is vastly\nsimplified. It will be an object with one property by table\nlabel, for example `q1$r1`. The value is an array of the\nrows displayed: the first element is the row's title and\nthe next N*2 elements are the percentage or stat value and\ncount, one per segment.\n"
                        qtype:
                          type: string
                          description: 'Question type of the underlying question (corresponds to

                            the lower-case XML tag, e.g. "radio").

                            '
                        segments:
                          description: 'Segments that were applied to this particular table. When

                            using pinned reports, tables display may have non-uniform

                            segments.

                            '
                          type: array
                          items:
                            type: object
                            properties:
                              title:
                                type: string
                                description: Segment's title.
                              cond:
                                type: string
                                description: 'Segment condition (Python expression ,e.g. "ALL" or

                                  "q1.r1").

                                  '
                              sg:
                                type: string
                                description: 'If is set and not null, this segment was stat

                                  tested against only other segments within the same

                                  `sg` value.

                                  '
                        qa:
                          type: array
                          items:
                            type: array
                            minItems: 2
                            maxItems: 2
                            items:
                              type: string
                          description: 'An array of QA codes for the underlying question. Each

                            array element is a 2-element array of the QA code

                            (e.g. "SHF\(r\)") and the human readable explanation

                            (e.g. "Rows are shuffled")

                            '
                        intent:
                          type: string
                          description: 'This is `null` for all tables except net summaries, where

                            it''s `summary`

                            '
                        obj:
                          type: string
                          description: 'The XML object that is the primary object driving this

                            table.  For a question that generates a single table, this

                            will be e.g. "q1".  For question that consists of multiple

                            tables (e.g. 2D radio grouped by rows), "q1,r1" .. "q1,r5".

                            '
                        tableType:
                          type: string
                          enum:
                          - simple
                          - numeric
                          - net
                          - stat
                          description: 'Set to `simple` (table contains percentages), `numeric`

                            (table contains stats such as mean), `net`" (additional

                            table  created for variable nets) or `stat` (summary table

                            for stats).

                            '
                  dlident:
                    type: string
                    description: 'The "DownLoad IDENT" value can be used to create a direct link

                      to a report run or to download data matching the report

                      segments.

                      '
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