GET

/Surveys/{id}/Metadata

Returns the complete metadata for a specific survey, including all variable definitions, sections, and value options.

Overview

The metadata endpoint provides the full structure of a survey. This includes information about all questions (variables), their types, labels, and possible answer values. Understanding the metadata is essential for interpreting the interview data.

Request

GET /Surveys/{id}/Metadata

Path Parameters

Parameter	Type	Description
`id`	string (GUID)	The unique identifier of the survey (from GET /Surveys)

Example Request URL

https://tsapi-demo.azurewebsites.net/Surveys/1e6cb0a1-2289-4650-9148-9fc3e6e129b2/Metadata

Response Structure

The response contains the complete survey metadata:

{
  "hierarchies": [],
  "name": "TS-001",
  "title": "Customer Experience Survey",
  "interviewCount": 3000,
  "languages": [
    {
      "languageId": "EN",
      "name": "English"
    }
  ],
  "variables": [],
  "sections": [
    {
      "label": { "text": "System", "altLabels": [] },
      "variables": [...]
    },
    {
      "label": { "text": "Demographics", "altLabels": [] },
      "variables": [...]
    }
  ]
}

Response Fields

Field	Type	Description
`name`	string	Survey short name/code
`title`	string	Survey title
`interviewCount`	integer	Total number of interviews
`languages`	array	Available languages for labels
`variables`	array	Root-level variables (if not using sections)
`sections`	array	Grouped sections containing variables
`hierarchies`	array	Optional hierarchical structures

Variable Object

Each variable represents a question in the survey:

{
  "variableId": "4",
  "ordinal": 0,
  "type": "single",
  "name": "Q2",
  "label": {
    "text": "Frequency of visit",
    "altLabels": [
      {
        "mode": "interview",
        "text": "Have you visited here before?",
        "languageId": "EN"
      },
      {
        "mode": "analysis",
        "text": "Visited before",
        "languageId": "EN"
      }
    ]
  },
  "values": {
    "values": [
      {
        "valueId": "0",
        "code": "0",
        "label": { "text": "No, this is the first visit" }
      },
      {
        "valueId": "1",
        "code": "1",
        "label": { "text": "I visited before within the year" }
      }
    ]
  },
  "maxResponses": 0
}

Variable Fields

Field	Type	Description
`variableId`	string	Unique identifier for the variable
`type`	string	Variable type (single, multiple, quantity, etc.)
`name`	string	Short name (e.g., Q1, Q2)
`label`	object	Main label with optional alternative labels
`values`	object	Possible values (for categorical types)
`maxResponses`	integer	Maximum allowed responses
`use`	string	Optional use type (e.g., "serial")

Variable Types

See Data Types for detailed information about each variable type:

single - Single response categorical
multiple - Multiple response categorical
quantity - Numeric values
character - Text/string values
date - Date values
time - Time values

Labels and Alternative Labels

Labels can have alternative versions for different contexts. The altLabels array contains labels for different “modes”:

interview - The question text shown to respondents
analysis - A shorter label for data analysis/reporting

Organizing Variables

Variables can be organized in two ways:

Root level: Variables defined directly in the variables array
Sections: Variables grouped into sections (e.g., “Demographics”, “Main Survey”)

Sections act like chapters in the survey, helping to organize related questions together.

Looped Variables

Some variables may contain loopedVariables - questions that are asked for each response to the parent variable. See the Data Types page for more details on nested structures.