{
"openapi": "3.0.1",
"info": {
"title": "TSAPI",
"description": "Sample TSAPI compliant RESTful web service implemented in a Visual Studio 2019 C# .NET Core 3.1 Web API project. This minimal working sample project can be cloned and customised to exchange surveys from different data provider companies. The internal processing and survey backing storage of a customised web service is unspecified, but the sample public API is a contract that must not change so that the service is TSAPI compliant. Return to the Welcome Page.",
"contact": {
"name": "TSASI Demo Service",
"url": "https://www.tsapi.net/",
"email": "admin@tsapi.net"
},
"version": "v1"
},
"paths": {
"/Surveys": {
"get": {
"tags": [
"Surveys"
],
"summary": "Lists summary information for all surveys.",
"responses": {
"200": {
"description": "The response body contains a serialized array of SurveyDetail",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SurveyDetail"
}
}
},
"text/xml": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SurveyDetail"
}
}
}
}
}
}
}
},
"/Surveys/{surveyId}/Metadata": {
"get": {
"tags": [
"Surveys"
],
"summary": "Fetches the metadata for a specific survey",
"parameters": [
{
"name": "surveyId",
"in": "path",
"description": "The Id of the survey metadata to retrieve.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The response body contains a serialized SurveyMetadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SurveyMetadata"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/SurveyMetadata"
}
}
}
}
}
}
},
"/Surveys/{surveyId}/Interviews": {
"get": {
"tags": [
"Surveys"
],
"summary": "Fetches some interview records for a specific survey.",
"parameters": [
{
"name": "surveyId",
"in": "path",
"description": "The Id of the survey being queried for data",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Start",
"in": "query",
"description": "The position of the first record to return. This number is 1-based.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "MaxLength",
"in": "query",
"description": "The total number of records to return. The API may return fewer if the number of records available is less than MaxLength.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "CompleteOnly",
"in": "query",
"description": "If True the API will return only interviews considered \"complete\" by the API system. If False, the API will select from all interviews",
"schema": {
"type": "boolean"
}
},
{
"name": "Variables",
"in": "query",
"description": "Return data from a subset of variables, specified as an array of variableId values. If empty, returns data for all variables.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "InterviewIdents",
"in": "query",
"description": "Return data from a subset of interviews, specified as an arrary of interviewId values. If empty, returns data for all interviews.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "DateFrom",
"in": "query",
"description": "Filter data on interviews created or updated on or after DateFrom",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "DateTo",
"in": "query",
"description": "Filter data on interviews created or updated on or before DateTo",
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "The response body contains a serialized SurveyMetadata.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Interview"
}
}
},
"text/xml": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Interview"
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"SurveyDetail": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique Id that the API system uses internally to identify a given survey",
"nullable": true
},
"name": {
"type": "string",
"description": "The human readable identifer assigned to the survey within the API system. For example, this may contain an internal job number such as \"TS-002\"",
"nullable": true
},
"title": {
"type": "string",
"description": "The human-readable name assigned to the survey within the API system. For example, \"Restaurant Satisfaction Survey\"",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing an available survey within the API system"
},
"ParentDetails": {
"type": "object",
"properties": {
"level": {
"type": "string",
"description": "The Level of the associated parent level. For example, in a household-person hierarchy, the\r\nparent_level_ident of the person level would be the level_ident of the\r\nhousehold level.",
"nullable": true
},
"linkVar": {
"type": "string",
"description": " The LinkVar is the name of the linking variable that appears in\r\nboth child and parent data sets.It must be a quantity or character type\r\nvariable. This variable must have the same name in the different (parent and\r\nchild) data sets.The variable used as the linking variable must, at the “parent”\r\nlevel, have unique and unduplicated data values in each record (that is, no two\r\nrecords can have the same value).",
"nullable": true
},
"ordered": {
"type": "boolean",
"description": " The Ordered is optional and identifies whether the data in the\r\ncorresponding level is ordered or not. It must be one of:\r\n - yes data in the parent level is ordered\r\n - no data in the parent level should be treated as unordered\r\nIf Ordered is not explicitly specified the value \"no\" is assumed."
}
},
"additionalProperties": false,
"description": "Object defining the parent and child relationship between hierarchical surveys"
},
"Language": {
"type": "object",
"properties": {
"languageId": {
"type": "string",
"description": "The unique Id that is used to refer to a language within the survey metadata and interview data. Although there is no restriction on language id, the intended values of this attribute are described in the official W3C XML version 1.0\r\nspecification as:- \"The values of the attribute are language identifiers as defined by IETF (Internet Engineering Task Force) RFC 3066, \"Tags for the Identification of\r\nLanguages\"(http://www.ietf.org/rfc/rfc3066.txt) or its successor on the Standards Track.\"",
"nullable": true
},
"name": {
"type": "string",
"description": "The human readable name used to refer to a language",
"nullable": true
},
"subLanguages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Language"
},
"description": "List of sub-languages (if any) that are grouped within the parent language (e.g. English => en-GB, en-US)",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing a language in use within a survey"
},
"AltLabel": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"description": "Signals whether a text should be used during interviewing and/or analysis. Two explicit modes are available: “interview” and “analysis”. In the absence of a mode specification, the appropriate text is assumed to be used in both modes. Allowable values are \"interview\" and \"analysis\"",
"nullable": true
},
"text": {
"type": "string",
"description": "Text value to use as an alternative label",
"nullable": true
},
"languageId": {
"type": "string",
"description": "Indicates that an alt label should be used when interviewing in a given language",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing an alternative text label"
},
"Label": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The main/default text used as a label",
"nullable": true
},
"altLabels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AltLabel"
},
"description": "List of alternative labels use that can be used instead of Text value in certain circumstances",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing a text label within a survey"
},
"ValueRange": {
"type": "object",
"properties": {
"from": {
"type": "string",
"description": "Defines the lower band of a range value. Must be lower than or equal to the \"To\" value",
"nullable": true
},
"to": {
"type": "string",
"description": "Defines the upper band of range value. Must be greater than or equal to the \"From\" value",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing a range of acceptable values for a variable response, e.g. 1 to 100"
},
"Value": {
"type": "object",
"properties": {
"valueId": {
"type": "string",
"description": "Unique identifier for a response value",
"nullable": true
},
"code": {
"type": "string",
"description": "Entry code (if-any) for a response value",
"nullable": true
},
"label": {
"allOf": [
{
"$ref": "#/components/schemas/Label"
}
],
"description": "The human readable label for a response value",
"nullable": true
},
"score": {
"type": "number",
"description": "The optional score attribute can only be used when the variable is of type single.\r\nIt allows score values to be assigned to the individual code values to be used for computing statistics such as Mean, Standard Deviation etc.\r\nThe score_value must be a number, and may be positive, negative or zero, with or without a decimal point and decimal places.The omission of a score\r\nimplies that records having that value code should be omitted from the base for any statistical computation for that variable.",
"format": "float",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing a closed-end question response"
},
"VariableValues": {
"type": "object",
"properties": {
"valueListId": {
"type": "string",
"description": "Identifier for this list of variable values. Can be used to identify value lists that are shared between variables",
"nullable": true
},
"range": {
"allOf": [
{
"$ref": "#/components/schemas/ValueRange"
}
],
"description": "Defines an overall range of legal values for a variable",
"nullable": true
},
"values": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Value"
},
"description": "Defines a set of response values for closed-end variables",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing an allowable set of values for a variable"
},
"OtherSpecifyVariable": {
"type": "object",
"properties": {
"parentValueId": {
"type": "string",
"description": "Defines the id of the closed end response that an other-specify is attached to",
"nullable": true
},
"variableId": {
"type": "string",
"description": "Unique identifier for this variable",
"nullable": true
},
"ordinal": {
"type": "integer",
"description": "The order of this variable within the overall survey",
"format": "int32"
},
"type": {
"type": "string",
"description": "The type of variable. Value values are: \"single\", \"multiple\", \"quantity\", \"character\", \"logical\", \"date\", \"time\"",
"nullable": true
},
"name": {
"type": "string",
"description": "Human-readable name for a variable",
"nullable": true
},
"label": {
"allOf": [
{
"$ref": "#/components/schemas/Label"
}
],
"description": "Label or question text for a variable",
"nullable": true
},
"use": {
"type": "string",
"description": "Special use type for this variable. Valid values are: \"serial\", \"weight\", \"language\", \"wave\", \"translation\"",
"nullable": true
},
"values": {
"allOf": [
{
"$ref": "#/components/schemas/VariableValues"
}
],
"description": "List of closed-end responses for this variable",
"nullable": true
},
"maxResponses": {
"type": "integer",
"description": "Maximum number of responses that can be given for this variable",
"format": "int32"
},
"loopedVariables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Variable"
},
"description": "Looped child variables for this variable",
"nullable": true
},
"otherSpecifyVariables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OtherSpecifyVariable"
},
"description": "List of other specify child variables for this variable (when type = Single or Multiple)",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing an “other specify” variable within a closed-end variable"
},
"Variable": {
"type": "object",
"properties": {
"variableId": {
"type": "string",
"description": "Unique identifier for this variable",
"nullable": true
},
"ordinal": {
"type": "integer",
"description": "The order of this variable within the overall survey",
"format": "int32"
},
"type": {
"type": "string",
"description": "The type of variable. Value values are: \"single\", \"multiple\", \"quantity\", \"character\", \"logical\", \"date\", \"time\"",
"nullable": true
},
"name": {
"type": "string",
"description": "Human-readable name for a variable",
"nullable": true
},
"label": {
"allOf": [
{
"$ref": "#/components/schemas/Label"
}
],
"description": "Label or question text for a variable",
"nullable": true
},
"use": {
"type": "string",
"description": "Special use type for this variable. Valid values are: \"serial\", \"weight\", \"language\", \"wave\", \"translation\"",
"nullable": true
},
"values": {
"allOf": [
{
"$ref": "#/components/schemas/VariableValues"
}
],
"description": "List of closed-end responses for this variable",
"nullable": true
},
"maxResponses": {
"type": "integer",
"description": "Maximum number of responses that can be given for this variable",
"format": "int32"
},
"loopedVariables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Variable"
},
"description": "Looped child variables for this variable",
"nullable": true
},
"otherSpecifyVariables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OtherSpecifyVariable"
},
"description": "List of other specify child variables for this variable (when type = Single or Multiple)",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing a variable or question within a survey"
},
"Section": {
"type": "object",
"properties": {
"label": {
"allOf": [
{
"$ref": "#/components/schemas/Label"
}
],
"description": "Human readable label used to name to a section",
"nullable": true
},
"variables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Variable"
},
"description": "List of variables",
"nullable": true
},
"sections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Section"
},
"description": "List of sub-sections (if any) within this section",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing a section within a survey. Sections are used to partition variables together into logical groups (e.g. Screener, System, Demographics, Main Survey etc…)"
},
"SurveyMetadataBase": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The human readable identifer assigned to the survey within the API system. For example, this may contain an internal job number such as \"TS-002\"",
"nullable": true
},
"title": {
"type": "string",
"description": "The human-readable name assigned to the survey within the API system. For example, \"Restaurant Satisfaction Survey\"",
"nullable": true
},
"interviewCount": {
"type": "integer",
"description": "The total number of interviews within the survey",
"format": "int32"
},
"languages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Language"
},
"description": "List of language objects defining the languages used within the survey",
"nullable": true
},
"variables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Variable"
},
"description": "List of variables (if any) defined at the root level of the survey",
"nullable": true
},
"sections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Section"
},
"description": "List of sub-sections (if any) defined at the root level of the survey",
"nullable": true
}
},
"additionalProperties": false
},
"Hierarchy": {
"type": "object",
"properties": {
"hierarchyId": {
"type": "string",
"description": "Unique identifier of a hierarchy item",
"nullable": true
},
"parent": {
"allOf": [
{
"$ref": "#/components/schemas/ParentDetails"
}
],
"description": "One or more parent elements may be defined for each level element.",
"nullable": true
},
"metadata": {
"allOf": [
{
"$ref": "#/components/schemas/SurveyMetadataBase"
}
],
"description": "The metadata (list of questions and variables) for a hierarchy item",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents a hierarchical sub-questionnaire within a main survey"
},
"SurveyMetadata": {
"type": "object",
"properties": {
"hierarchies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Hierarchy"
},
"description": "List of hierarchical questionnaires (if any) within a survey",
"nullable": true
},
"name": {
"type": "string",
"description": "The human readable identifer assigned to the survey within the API system. For example, this may contain an internal job number such as \"TS-002\"",
"nullable": true
},
"title": {
"type": "string",
"description": "The human-readable name assigned to the survey within the API system. For example, \"Restaurant Satisfaction Survey\"",
"nullable": true
},
"interviewCount": {
"type": "integer",
"description": "The total number of interviews within the survey",
"format": "int32"
},
"languages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Language"
},
"description": "List of language objects defining the languages used within the survey",
"nullable": true
},
"variables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Variable"
},
"description": "List of variables (if any) defined at the root level of the survey",
"nullable": true
},
"sections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Section"
},
"description": "List of sub-sections (if any) defined at the root level of the survey",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing a survey and all of its metadata (information about questionnaire variables)"
},
"VariableDataItem": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "A specified variable response",
"nullable": true
},
"state": {
"type": "string",
"description": "(Optional) state of a response. Permitted values are \"selected\", \"notSelected\", \"notShown\"\r\nUsed to provide information about exactly which closed end responses were shown/selected/unselected in a given iterview",
"nullable": true
},
"loopedVariableData": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VariableData"
},
"description": "(Optional) Data for looped variables which are child responses connected to a VariableDataItem",
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing a data value or response for a variable in an interview"
},
"VariableData": {
"type": "object",
"properties": {
"variableId": {
"type": "string",
"description": "The Id of the variable to which a set of variable data relates to",
"nullable": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VariableDataItem"
},
"description": "List of responses given for this variable",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents the response(s) given to a variable in the survey"
},
"Level": {
"type": "object",
"properties": {
"levelId": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"HierarchicalInterview": {
"type": "object",
"properties": {
"level": {
"allOf": [
{
"$ref": "#/components/schemas/Level"
}
],
"description": "Indicates which level of the hierarchy an interview is associated with",
"nullable": true
},
"interviewId": {
"type": "string",
"description": "Unique identifier of an interview",
"nullable": true
},
"date": {
"type": "string",
"description": "Date interview was last changed",
"format": "date-time"
},
"complete": {
"type": "boolean",
"description": "Indicates whether the interview is considered a Complete interview or not"
},
"responses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VariableData"
},
"description": "List of responses given within the interview",
"nullable": true
},
"hierarchicalInterviews": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HierarchicalInterview"
},
"nullable": true
}
},
"additionalProperties": false,
"description": "Object represents a hierarchical interview with a main parent interview"
},
"Interview": {
"type": "object",
"properties": {
"interviewId": {
"type": "string",
"description": "Unique identifier of an interview",
"nullable": true
},
"date": {
"type": "string",
"description": "Date interview was last changed",
"format": "date-time"
},
"complete": {
"type": "boolean",
"description": "Indicates whether the interview is considered a Complete interview or not"
},
"responses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VariableData"
},
"description": "List of responses given within the interview",
"nullable": true
},
"hierarchicalInterviews": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HierarchicalInterview"
},
"nullable": true
}
},
"additionalProperties": false,
"description": "Object representing a completed interview in a survey"
}
}
}
}