Getting Started

This guide will help you understand how to use TSAPI to retrieve survey data from any TSAPI-compliant system.

What are GET Requests?

An API GET request is like asking a server for information. You send a message (the request) to a specific place on the internet (the server), asking for something. The server then gives you back the information you requested.

Importantly, when you use a GET request, you're only asking for information, not making any changes. TSAPI defines a set of GET requests to retrieve Surveys, Survey Metadata, and Survey Interviews from whichever server is hosting them.

Understanding Endpoints

In the context of API GET requests, an “endpoint” is a specific URL that represents a resource or a collection of resources on a server. The endpoint is like a unique address for a particular piece of data.

For example, if you were working with a weather API, you might have an endpoint like:

https://api.weather.com/forecast

In this case, /forecast is the endpoint. It tells the server that you're interested in weather forecast information.

TSAPI Endpoints Overview

TSAPI defines three main endpoints:

Endpoint	Description
`GET /Surveys`	List all available surveys
`GET /Surveys/{id}/Metadata`	Get metadata for a specific survey
`GET /Surveys/{id}/Interviews`	Get interview data for a specific survey

Your First Request

Let's start by listing all available surveys. Using the TSAPI demo server:

GET https://tsapi-demo.azurewebsites.net/Surveys

This returns a list of surveys available to you:

[
  {
    "id": "1e6cb0a1-2289-4650-9148-9fc3e6e129b2",
    "name": "TS-001",
    "title": "Customer Experience Survey"
  },
  {
    "id": "a4bd7eed-88df-4a57-86d6-396e3698022e",
    "name": "TS-002",
    "title": "Cereal Awareness Survey"
  }
]

Each survey has a unique id, a short name, and a descriptive title. You'll use the id to fetch more details about a specific survey.

Getting Survey Metadata

Once you have a survey ID, you can fetch its metadata. This includes information about the survey structure, variables, and possible values:

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

The response includes:

Survey name and title
Interview count
Available languages
Variables (questions) with their types, labels, and possible values
Optional sections for organizing variables

Getting Interview Data

Finally, you can retrieve the actual interview responses:

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

Caution: Large Datasets

Without parameters, this returns ALL interviews. For large surveys, use parameters like MaxLength and Start to paginate results.

Using Parameters

You can add parameters to your GET requests to filter and paginate results. Parameters are added to the URL after a ? and separated by &:

GET https://tsapi-demo.azurewebsites.net/Surveys/{id}/Interviews?MaxLength=50&CompleteOnly=true

Available parameters for interview requests:

Parameter	Type	Description
`Start`	Integer	Starting interview number
`MaxLength`	Integer	Maximum number of interviews to return
`CompleteOnly`	Boolean	Return only completed interviews
`Variables`	Array	Filter to specific variable IDs
`InterviewIdents`	Array	Filter to specific interview IDs
`DateFrom`	String	Start date filter (YYYY-MM-DD)
`DateTo`	String	End date filter (YYYY-MM-DD)

Example: Combining Parameters

This request fetches a maximum of 50 completed interviews, conducted between October 5, 2021 and November 28, 2021:

GET https://tsapi-demo.azurewebsites.net/Surveys/1e6cb0a1-2289-4650-9148-9fc3e6e129b2/Interviews?MaxLength=50&CompleteOnly=true&DateFrom=2021-10-05&DateTo=2021-11-28

Try It Yourself

You can explore the TSAPI endpoints using these tools:

Demo Survey

Interactive demo covering all question types

Postman Collection

Ready-to-use GET request examples

Next Steps

Learn about all API endpoints in detail
Understand data types in survey metadata
Check the FAQ for common questions