/api/v1/interviews deprecated

The /api/v1/interviews endpoint has been marked as deprecated. Unfortunately I cannot find a full replacement for it. There is /api/v1/questionnaires/{id}/{version}/interviews, but that one does not seem to allow for filtering by interview status. What approach would you suggest for searching for interviews with a specific status?

Hello @tschoel,

the following API endpoint will give you the list of interviews collected on a particular questionnaire+version:

/api/v1/questionnaires/{id}/{version}/interviews

Indeed, it does not allow filtering based on the status of interviews, so you will be getting a full list of interview records, but each interview record will contain a Status field, which you can utilize to narrow down the list of interviews to only ones in a particular status, such as, for example, “Completed

Depending on what you want to do next, it may be reasonable to consider exporting all data as a data export, and then operate already on the interview__diagnostics file.

Hope this helps!

Best, Sergiy

Hi Sergiy,

Thanks for taking the time to reply. It feels a bit inefficient to always query the entire set of interviews, especially with the 40 records hard limit that you have (or has that limit been lifted by any chance?).

Exports are what I am currently using (they do come with the ability to filter by status in v2, too). Yet, since I need to check for new interviews with a specific status every 30min that method keeps cluttering HQ’s export history quite a bit. I would rather be able to check if anything new exists at all in the required status before I run the export.

I had also hoped that /api/v1/statistics might give me that information but I cannot seem to get it to provide me with any meaningful information whatsoever.

If you have an idea how to do this with fewer exports in the exports list, let me know. Otherwise, you may consider this a feature request for filtering capabilities on the /api/v1/questionnaires/{id}/{version}/interviews endpoint.

Thanks again and kind regards,
Thorsten

We deprecated this endpoint and replaced by another one, although clearly not well-documented - in 20.06 we started using new api ‘format’ called GraphQL and slowly started moving some functionality there, including this specific endpoint of getting a list of interviews (with filtering).

We’re working in making that api more easily discoverable and usable, but you can already start using it. GraphQL works by sending POST requests to the [baseurl]/graphql endpoint with a payload containing a specific query:

     POST https://localhost:9700/graphql
     {
       interviews {
         filteredCount
         nodes {
           id
           responsibleId
           errorsCount
           status
         }
       }
     }

for example will return all the interviews and display listed fields for each interview. In order to filter the list, you can add where condition:

     POST https://localhost:9700/graphql
     {
       interviews (where: {
            questionnaireId: "1c1785b2a4d94041bf3ebc2c7520934c"
            status:COMPLETED
        }) {
         filteredCount
         nodes {
           id
           responsibleId
           errorsCount
           status
         }
       }
     }

will return only completed interviews from the specific questionnaire id.

If you’re using Python, ssaw package helps to hide away the boilerplate code:

 from ssaw import Client, InterviewsApi
 
 client = Client('http://localhost:9700', 'username', 'password')
 interview_list = InterviewsApi(client).get_list(
   questionnaire_id="1c1785b2a4d94041bf3ebc2c7520934c",
   status="COMPLETED")
 for i of interview_list:
   print(i)
1 Like