Data Format


The Required elements at root level:

 "CaseData" – which is the data

 "MetaData" – which is the description of the data

 "ImportContext" – which has settings for the system

All fields are case sensitive, there must not be any duplicates.

This document describes the three elements in order.

Case Data

Case Data Using JSON

There are three default fields for each respondent:

RespondentID of type OpenNumeric

ResponseDate of type DateTime

Weight of type OpenNumeric

The names of the default fields can be over written in the import context. Default values can be applied for response date and weight suitable when all respondents share the same values.

So, assuming we are setting ID, date and weight per respondent, the first three elements in a respondents case data would normally be:

"RespondentID": "1","ResponseDate": "2021-12-12","Weight": "0.9"

The order of the fields doesn't matter in either the case or metadata

Then the values for all the variables that are defined in the metadata as key value pairs.

Example Case Data:

    {"RespondentID": "1","ResponseDate": "2021-12-12","Weight": "0.9","RespondentAge": "35","PetName": "Fido","Country": [ "1" ],"Brands": [ "1", "2" ],"Scale":["5"]},
    {"RespondentID": "2","ResponseDate": "2021-12-13","Weight": "1.1","RespondentAge": "32","PetName": "Rover","Country": [ "2" ],"Brands": [ "2" ],"Scale":["4"]},
  {"RespondentID": "3","ResponseDate": "2021-12-14","Weight": "1","RespondentAge": "21","PetName": "Tyson","Country": [ "2" ],"Brands": [ "2", "3" ],"Scale":["3"]},
  {"RespondentID": "4","ResponseDate": "2021-12-15","Weight": "1","RespondentAge": "53","PetName": "Rocky","Country": [ "3" ],"Scale":["2"]}],

Case Data using CSV

Case data can also be uploaded via a CSV file. This should be formatted according to the RFC 4180


The first line should be the question codes.

Use CSV case data for large data sets, the file sizes are smaller.

Commas and new lines are supported in fields enclosed in double quotes:

”1”,”This is the first line

this the second line”,”3”

If a double quote is to be imported it must be preceeded by a double quote.

"1","This field contains a ""quoted"" section","3"

The string variable aboce would be imported as:

This field contains a "quoted" section

Using double quotes is not obligatory if none of the above considerations apply.

Uploading data in CSV is a two stage process. 

First POST the file via the rest method

/api/v1/project/nnnnnn/interactive_import/upload –

Eg using c#

request.AddParameter("multipart/form-data; boundary=----
WebKitFormBoundary7MA4YWxkTrZu0gW", "------
WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"\";
filename=\"exampleDataApiCSV.csv\"\r\nContent-Type: text/csv\r\n\r\n\r\n------
WebKitFormBoundary7MA4YWxkTrZu0gW--", ParameterType.RequestBody);

Then call the import method adding the file identifier which is the response to the upload method:

"tempFileGuid": "03266da5-c9a0-41ce-8fa1-7dc18e63e33e",
"fileName": "exampleDataApiCSV.csv"


Metadata describes the data, variable types, answer codes and values. The required elements as per

case data, a RespondentID, ResponseDate and Weight. Each element needs to have Code, Text, Type

and optionally the AnswerAlternatives array.

Example metadata demonstrating different question types of variables :

  {"Code":"RespondentAge","Text":"How old are you?","Type":"OpenNumeric","AnswerAlternative":null},
  {"Code":"PetName","Text":"What is the name of your pet?","Type":"OpenString","AnswerAlternative":null},
  {"Code":"Country","Text":"Where you are from?","Type":"SingleChoice",
  {"Code":"Brands","Text":"Which brands do you use?","Type":"MultiChoice",
  {"Code":"Scale","Text":"Enter a rating(1to5)?","Type":"SingleChoiceScale",

Limits for field sizes:
Question code is limited to 50 chars, Question text is 500 chars.
Answer code is of data type int, i.e. a 4 byte signed integer, Answer text 500 chars.


Question codes are limited in length to 50 characters and if it is required that they will be exported in SPSS format should start with a letter, although numeric codes are supported.


Valid Types are:







It is possible to over write previous metadata for question texts and answer texts. It is not possible to change the question type, e.g. from single choice to single choice scale. This can be done in the system if required.


This an element with an array of Code and Text fields. 


Example import context:


The following section describes the values supported in the import context-


”1” for case data only, ”2” for case and meta data. 

When using JSON with type ”1” the metadata element must still be sent with the mandatory RespondentID, ResponseDate and Weight elements, no other metadata information should be sent. When using CSV all metadata must be supplied with both ImportTypes


Valid values are:

 Xml = 1, (Deprecated)

 Spss = 2,

 TripleS = 3,

 Excel = 4,

 Unicom = 5,

 Json = 6,

 DataApiCSV = 7

For the Data Import API the value will be 6 for regular imports and 7 for the CSV case data.

Stacked Data

If the data set is a loop or grid associated with existing respondents set this to true


For stacked data this is used to define which variables are the keys or iterators for the loop as a comma seperated list. For instance, this couild be the brand that is passed into the loop.


Set to true if metadata should be overwritten or updated.


Set to true if this data should be treated as an update to an existing dataset rather than new data. Respondents are mapped on RespondentID.


Set to true if using combination of new and existing respondents in the import.


The metadata mapping to use for the imported data. In most cases this will not be relevant for the data API.


How to group answers in answer blocks.

Allowed values:

"Smart detection of similar answer lists" (Default value) compare texts in answer list to create answer

blocks that have sets of matching texts.

"Identical answer lists" Use same answer block when all texts and codes match

"No sharing" create new answer block for each question, every question will have its own answer block

TempFileGUID + FileName

Used in uploading CSV data - see above


Set the respondent id variable name if it should be overridden, defaults to RespondentId


Use this to over ride the default ”ResponseDate” variable. Must be a date variable. See below regarding format.


Set variable name to use for weight if not ”Weight” – must be open numeric


Set a default response date for all respondents, useful when there is no date variable


Set a weight for all respondents, set to "1" when there is no weight to be applied to the data


Set the date format string to be applied when reading dates. Default is yyyy-MM-dd.

For example: "DateFormat": "yyyy-M-d" to support dates in 2021-2-1 format.


a comma separated list of values to exclude from import.


Required when using the hfilter import end point, this the code of the question used for the hierarchy.