Retrieving Interviews through API

Hi There,

This is just a general question.

When getting an Interview through the API, is it possible to return the ‘Value’ field instead of the ‘Title’ field for Single-select question types?

Also for List question types, is it possible to return each list item separately instead of in a comma delimited or tab delimited string? We have List Items that contains a coma or sometimes a Tab and this makes it difficult to read through the API.

Kind Regards
Eugene Ehlers

Eugene, could you please clarify which API endpoint(s) you’re trying to use?

1 Like

Hi Arthur,

We are using the following API

GET /api/v1/interviews/{id}

Eugene, let me talk with the dev team to see if there’s a method I’m not seeing.

Here are the work-arounds I immediately see (which both involve getting the answer options from elsewhere and applying them to your data set):

  • Manually compile the “title”-“value” mapping from your questionnaire in Designer so that you can replace the “title” with the “value” in your data set. This is manual, but a fine quick-and-dirty solution.
  • Recover the “title”-“value” mapping from the JSON representation of the questionnaire by fetching it via theGET /api/v1/questionnaires/{id}/{version}/document API endpoint, parsing the file, and replacing the “title” with the “value” in your data set. This is a more elegant programmatic solution, but more fixed costs of figuring out the endpoint and the JSON qnr structure.

My guess is that we wanted the endpoint you’re using to return exactly what the end user sees in the UI. But the problem is that some question types, like single-select questions, have both a “title” and “value” representation. From what you’re saying, the endpoint only returns the “title” representation.

1 Like

The scenario is that we are updating a longitudinal relational database with the data collected through Survey Solutions and using the api to retrieve HQ approved interviews, update the external database with the collected information, if the update to the longitudinal database fails (e.g. temporal integrity issues), we use the api to unapproved the interview and transfer it to the team that deals with these issues. The data export process is too cumbersome to use in this scenario and currently we resort to accessing the Survey Solutions database directly. This is obviously not the ideal, but as per your description there is just to many hoops to jump through to make the use of the api productive in this scenario.

Let us discuss that functionality with developers and see if we can extend the current API to accommodate your request. We will get back to you shortly.

Kobus and Eugene,

My apologies. Due to insufficient caffeination, I misread the endpoint you’re using, and thereby misunderstood what you’re trying to do.

Reading your message too quickly, I thought you were using GET /api/v1/interviews instead of GET /api/v1/interviews/{id}–and thus thought you were trying to parse the identifying variables for each interview, rather than answers to all questions in the interview.

If your objective is, effectively, to get interview data, analyze it, and reject interviews with problems, why not download data for a set of interviews rather than request interview data interview by interview?

If that idea sounds appealing, here’s how you might implement it:

  • Ask the server to download data. When doing so, you can specify, interview status (e.g., only ApprovedByHeadquarters), completion dates (e.g., interviews whose status has changed between from and to), export type (e.g., Stata or SPSS, which give you “title” and “value” representations of data, or tabular, which gives only “value” representation). See the POST /api/v1/export/{exportType}/{id}/start endpoint
  • Check on the status of downloaded. See the GET /api/v1/export/{exportType}/{id}/details endpoint.
  • React to the status of downloaded data. Look at the ExportStatus part of the server response. If data are not ready yet, wait and check the status again in a few seconds. If data are ready, download them.
  • Download the requested file. See the GET /api/v1/export/{exportType}/{id}
  • Run your business logic to determine what to unapprove and reassign.
  • Unapprove and reassign select interviews.

During my own in-office, desktop testing, this has performed fairly fast and well for a similar routine that I run.

If you write, I’d be happy to share some R scripts that do (virtually) every part of what’s described above. Part of them are referenced in this thread.

We are not very enthusiastic about going the bulk download route, for several reasons:

a. This leaves downloaded data with confidential information on the file system – yet another data protection issue to manage
b. Parsing the data from the downloaded data files is quite a different procedure from parsing the json data potentially available from the endpoint, specifically processing the data for a single questionnaire involves combining records pertaining to that questionnaire from several different data files (in our case no less than 22 files!).
c. We have build an interactive front end that surfaces concepts we use in our long term longitudinal surveillance of all households/individuals in a defined geographic area that isn’t catered for in SurveySolutions and this interactive frontend doesn’t fit easily within the batch approach.
d. The objective is not just to analyse the retrieved interview data, but to update longitudinal relational database with each retrieved data record and respond on a record by record basis.

1 Like

Kobus Herbst,

batch download seems to be suitable for the tasks that you’ve outlined. Download the whole dataset (protect it with a password if so desired for privacy reasons), select the updated records and push them into your relational database. I don’t know of its structure, but I assume it also consists of multiple tables, which may roughly coincide with the 22 files survey solutions produces for your questionnaire template. Have your frontend talk with your database rather than Survey Solutions directly.

Eugene, you wrote that your List items sometimes contain a Tab, how do you enter it on a tablet?

1 Like


We pre-load some of our list questions and the pre-loaded data might contain tab values. The format of our pr-loaded data generally looks something like:
“Surname, Name1 Name2 (BCDFG-H) - FEM - 31”.

The Interviewers are also able to add to the existing list of items and they typically add items in the following format:
“Surnname, Name1 Name2 - MAL - 50”.

Eugene Ehlers

If the files that you preload contain TAB characters in the content, rather as delimiters only, they should be filtered out and replaced with something else. Otherwise your preloaded data will differ from what you intended to preload.

In your description you don’t show where the TAB character may occur and what is it’s role.

If I were given a file to preload


I would have converted it to the file


Best, Sergiy

Sigh, I guess I will have to continue accessing Survey Solution directly.