openapi: 3.2.0 info: title: Decipher Rest Data 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: Data paths: /surveys/{survey}/data: get: operationId: getSurveyData summary: Download data description: 'Returns list of survey responses filterable through a robust set of query parameters. ## Formats The following data formats can be requested using the `format` parameter. Format | Description --------------|------------------ `tab` | A tab-delimited format with column headings. `tab_uq` | A tab-delimited format with column headings and unquoted values. `fwu` | A fixed-width format with offsets based on unicode characters. `fw` | A fixed-width format with offsets based on raw bytes `flat` | A flattened format containing OE data `flat_all` | A flattened format containing non-blank data for all fields. `pipe` | A pipe delimited format with column headings. `csv` | A comma delimited format with column headings. `cb` | An IBM column binary. `json` | Standard JSON. `jsonl` | JSON with labeled values (returns value labels instead of numeric codes). `spss` | The SPSS default format (SPSS 15). `spss16` | SPSS 16+ (*.sav) file with Unicode Support (zipped). `spss15` | SPSS 15 (*.sav) file (zipped). `spss16_oe` | SPSS 16+ (*.sav) file including all OE data (zipped). `spss_data` | A fixed-width data file and SPSS script file (zipped). ## Content Types Content type differs dependent on the requested `format`. Content Type | Format --- | --- application/json | json, jsonl text/plain; charset=utf-8 | tab, tab_uq, fw, flat, flat_all, pipe, csv, fw, fwu application/octet-stream | cb application/zip | spss, spss15, spss16, spss16_oe, spss_data Available keywords: `all, qualified, terminated, overquota, partials, everything`.' tags: - Data parameters: - $ref: '#/components/parameters/survey' - name: format in: query description: The data format requested. example: flat schema: type: string enum: - tab - tab_uq - fw - flat - flat_all - pipe - csv - fwu - cb - json - jsonl - spss - spss15 - spss16 - spss16_oe - spss_data default: tab - name: layout in: query description: The layout ID, either hardcoded or retrieved using Layouts API. Standard layout is used by default if no layout ID is specified. example: 123456 schema: type: integer - name: fields in: query description: The list of field names to retrieve. schema: type: array items: type: string examples: oneField: value: - q1 multipleFields: value: - q1 - q2 - q3 - name: start in: query description: 'Start date. Setting start will restrict the API results to respondents who were last active in the survey after that "start" parameter. This corresponds to the "date" field in downloads. This date field is not affected by data edits. ' example: 2020-01-01T00:00Z schema: type: string format: ISO-8601 - name: end in: query description: 'End date. Setting end date will restrict the API results to respondents who were last active in the survey before the "end" parameter. This corresponds to the "date" field in downloads. This date field is not affected by data edits. ' example: 2020-12-31T00:00Z schema: type: string format: ISO-8601 - name: cond in: query description: "The condition required to retrieve the participant. This is a Python\ncondition as if you would enter in survey logic or crosstabs. For\nexample, `qualified and q3.r2` retrieves only participants that were\n`qualified` and answered `q3` as `r2`. \n\nYou can also pass a crosstab id with `xt:` where the ``\nis the last part of the crosstab report url. For example if the url is:\n`https://example.decipherinc.com/apps/report/selfserve/545/231002#!/report/nx09qh7uvq455tgg`\nthe `` would be `nx09qh7uvq455tgg`. This extracts based on those who belong to\nthe first segment of the Crosstabs report. You can extract data for a different segment\nby specifying it this way: `xt::2`, 2 being the segment number.\n" example: qualified and q1.r1 schema: type: string default: all - name: stacking in: query description: 'Argument to specify stacked data file. Options are `top` which outputs all the non-looped variables and `label` which outputs the looped data for the specific loop label. ' example: top schema: type: string - name: language in: query description: Get the datamap in a different language. Supported for spss variants only. Specify the language name as configured in the survey.xml (e.g. french or spanish_mexico). example: french schema: type: string - name: meta in: query description: "Argument to specify miscellaneous options to control the results. The \navailable options are:\n- modified - Makes the API output and filter results by the record's \n`data_updated` field, rather than `last_activity`.\n- date - Include an additional $date field in the output that will show\nthe respondent's completion time in ISO-8601 format.\n" example: modified,date schema: type: array items: type: string responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/surveyData' x-codeSamples: - lang: Curl source: 'curl -H x-apikey: {api_key} -X GET {server}/api/v1/surveys/{survey}/data?format=json ' - lang: Cli source: 'beacon get surveys/{survey}/data format=json > myfile.json ' post: operationId: createSurveyData summary: Download data description: 'This is equivalent to the GET request. However GET requests are limited to around 1000-character URLs. We include a POST version that does not generate data but allows for any amount of fields to be specified. Available keywords: `all, qualified, terminated, overquota, partials, everything`.' tags: - Data parameters: - $ref: '#/components/parameters/survey' requestBody: content: application/json: schema: type: object properties: format: description: The data format requested. enum: - tab - fw - flat - flat_all - pipe - csv - fwu - cb - json - spss - spss15 - spss16 - spss16_oe - spss_data type: string default: tab example: json layout: description: 'The layout ID, either hardcoded or retreived using Layouts API. ' type: integer example: 123456 fields: description: The list of field names to retrieve. type: array items: type: string example: - q1 start: description: 'Start date. Setting start will restrict the API results to respondents who were last active in the survey after that "start" parameter. This corresponds to the "date" field in downloads. This date field is not affected by data edits. ' type: string format: ISO-8601 example: 2020-01-01T00:00Z end: description: 'End date. Setting end date will restrict the API results to respondents who were last active in the survey before the "end" parameter. This corresponds to the "date" field in downloads. This date field is not affected by data edits. ' type: string format: ISO-8601 example: 2020-12-31T00:00Z cond: description: 'The condition required to retrieve the participant. This is a Python condition as if you would enter in survey logic or crosstabs. For example, `qualified and q3.r2` retrieves only participants that were `qualified` and answered `q3` as `r2`. ' type: string default: all example: qualified and q1.r1 stacking: description: 'Argument to specify stacked data file. Options are `top` which outputs all the non-looped variables and `label` which outputs the looped data for the specific loop label. ' type: string example: top meta: description: "Argument to specify miscellaneous options to control the results. The \navailable options are:\n- modified - Makes the API output and filter results by the record's \n`data_updated` field, rather than `last_activity`.\n- date - Include an additional $date field in the output that will show\nthe respondent's completion time in ISO-8601 format.\n" type: array items: type: string example: - modified - date responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/surveyData' /surveys/{survey}/datamap: get: operationId: getSurveyDatamap summary: Retrieve datamap description: 'Survey datamaps are the structured representation of the survey questions and configurations. The following formats are supported for datamaps. ## Formats Format | Description --------------|------------------ `json` | Standard JSON. `json_stacked` | A JSON object where the keys are the loop IDs and the values are the datamap for the stacked configuration. `html` | Plain HTML. `text` | Plain text. `tab` | A tab-delimited format with column headings. `xlsx` | Microsoft Excel spreadsheet with column headings `fw-html` | A fixed-width format with offsets based on raw bytes (HTML) `fw-tab` | A fixed-width format with offsets based on raw bytes (Tab) `fw-text` | A fixed-width format with offsets based on raw bytes (Text) `cb-html` | An IBM column binary (HTML). `cb-tab` | An IBM column binary (Tab). `cb-text` | An IBM column binary (Text). `uncle` | ? `sss` | Triple-S 1.5 XML `sas` | ? `quantum` | ? `spss_fw` | SPSS format with fixed-width start/stop annotations `spss_tab` | SPPS format in tab delimited format `netmr-tab` | Net MR datamap in fixed-width format `netmr-csv` | Net MR datamap in comma-delimited format' tags: - Data parameters: - $ref: '#/components/parameters/survey' - name: format in: query required: true description: The requested response format. example: json schema: type: string enum: - json - json_stacked - html - text - tab - fw - xlsx - fw-html - fw-tab - fw-text - cb-html - cb-tab - cb-text - uncle - sss - sas - quantum - spss_fw - spss_tab - netmr-tab - name: layout in: query description: The layout ID. Standard layout is used by default if no layout ID is specified. example: 12345 schema: type: integer - name: qa in: query description: Include QA codes (only available for HTML formats) example: true schema: type: boolean - name: language in: query description: Get the datamap in a different language. Supported for html, text, tab, any fw, json, json_stacked, spss_fw and sss only. Specify the language name as configured in the survey.xml (e.g. french or spanish_mexico). example: french schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/surveyDatamap' x-codeSamples: - lang: Curl source: 'curl -H x-apikey: {api_key} -X GET {server}/api/v1/surveys/{survey}/datamap?format=json ' - lang: Cli source: 'beacon get surveys/{survey}/datamap format=json > myfile.json ' /surveys/{survey}/layouts: get: operationId: getSurveyLayouts summary: Retrieve all data layouts description: 'List all layouts configured for survey. Layouts can be configured using the Data Layout Manager.' tags: - Data parameters: - $ref: '#/components/parameters/survey' responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/surveyLayout' x-codeSamples: - lang: Curl source: 'curl -H x-apikey: {api_key} -X GET {server}/api/v1/surveys/{survey}/layouts ' - lang: Cli source: 'beacon get surveys/{survey}/layouts > myfile.json ' /surveys/{survey}/layouts/{layout_id}: get: operationId: getSurveyLayout summary: Retrieve a single data layout description: Retrieves the data layout for the provided layout ID. tags: - Data parameters: - $ref: '#/components/parameters/survey' - name: layout_id in: path description: The data layout ID. example: 123 required: true schema: type: integer responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/surveyLayout' '404': description: Not Found content: application/json: schema: type: object properties: $error: type: string description: error description $code: type: integer description: http error code (404) extra: type: string example: $error: Layout not found $code: 404 extra: null x-codeSamples: - lang: Curl source: 'curl -H x-apikey: {api_key} -X GET {server}/api/v1/surveys/{survey}/layouts/{layout_id} ' - lang: Cli source: 'beacon get surveys/{survey}/layouts/{layout_id} ' /surveys/{survey}/coverage: get: operationId: getSurveyCoverage summary: Execute coverage report description: 'The coverage report shows number of participants shown each question, split by the desired segments. It can be called with a Crosstabs dlident produced by crosstabs (looks like ~123.456) or by explicitly specifying Crosstab segment conditions (e.g. "q1.r1,q1.r2") and a precondition (like "qualified")' tags: - Data parameters: - $ref: '#/components/parameters/survey' - name: segments in: query required: true description: Comma-separated list of segments to split by example: q1.r1,q1.r2,q1.r3 schema: type: string - name: precondition in: query description: Precondition example: qualified schema: type: string - name: config in: query description: Crosstabs dlident. Specify EITHER config or segments and precondition example: ~123.456 schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: segments: description: segments used for the calculations type: array items: type: object properties: count: type: integer description: participants in the segment cond: type: string description: condition for segment membership title: type: string description: human-given title example: - count: 10 cond: q1.r1 title: R1 segment questions: type: array description: questions and their answered/shown counts per segment example: - label: q1 title: Question 1 shown: - 5 answered: - 4 items: type: object properties: shown: type: array description: participants who saw this question in each segment items: type: integer answered: type: array description: participants who answered this question in each segment items: type: integer label: type: string description: question label title: type: string components: schemas: surveyDatamap: type: object properties: variables: type: array items: $ref: '#/components/schemas/surveyVariables' questions: type: array items: type: object properties: variables: type: array items: $ref: '#/components/schemas/surveyVariables' grouping: type: string example: rows type: type: string example: number qtitle: type: string example: How likely are you to recommend our company, product or service to a friend or colleague? qlabel: type: string example: Q1 surveyData: type: object properties: status: description: The survey completion status. example: 1 type: integer uuid: description: The survey `uuid`. example: jwy3kwppp4yuqg86 type: string format: uuid vmobiledevice: description: The respondent's mobile device code. example: 5 type: integer url: description: The survey builder url. example: http://release.decipherinc.com/survey/selfserve/1a/123456 type: string vbrowser: description: The respondent's browser code. type: integer example: 11 qtime: description: The elapsed time (seconds) from survey start to complete. example: 56.235 type: number format: float list: example: 0 type: integer dcua: example: .. type: string markers: example: qualified,/totalQuota/Total type: string record: example: 1 type: integer session: description: Unique user session ID. example: cwsps4gewqc0p175 type: string format: uuid vos: description: The respondent's operating system (os). example: 13 type: integer date: example: 09/02/2020 14:52 type: string vlist: example: 1 type: integer Q1r1: description: An example question response example: '8' type: string Q2a: description: An example question response example: I thought it was great. type: string Q2b: description: An example question response example: I thought it was not so great. type: string surveyLayout: type: object properties: id: type: integer description: The resource ID. createdBy: type: string format: email description: Created by user email. createdOn: type: string format: date-time description: Layout creation timestamp. description: type: string description: The layout description. updatedOn: type: string format: date-time description: Last updated timestamp. updatedBy: type: string format: email description: Last updated by user email. variables: description: 'List of survey variables ' type: array items: type: object properties: altlabel: type: string description: Alternative label for variable. fwidth: type: integer description: The number of characters variable occupies (for fixed-width layouts). label: type: string description: Unique variable label. minStart: type: integer description: The offset the variable should start at. new: type: boolean description: True if variable did NOT exist on previous datamap. qlabel: type: string description: The parent question label. qtype: type: string description: Question type of parent question. example: radio shown: type: boolean description: True if variable is shown in current layout. src: type: string description: 'The variable''s source. Value | Description ----- | ----------- `g` | Virtual `s` | Survey `y` | System ' example: g enum: - g - s - y title: type: string surveyVariables: type: object properties: vgroup: type: string qtitle: type: string colTitle: type: string title: type: string rowTitle: type: string label: type: string row: type: string type: type: string col: type: string qlabel: type: string values: type: array items: type: object properties: value: type: integer title: type: string 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