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