Interview-Id

Overview

The Interview-Id is a unique, random, immutable string that defines a given patient’s single interview with Infermedica API.

A single interview with Infermedica API

In this context, “a single interview” may span across multiple calls to the API and usually refers to a full symptom-checking interview - from the moment the user initiates the interview to when they get all of the required recommendations and decide to finish the interaction.

The Interview-Id value should be passed to Infermedica API during each request via the HTTP header: Interview-Id.

Who creates an Interview-Id?

Whenever a patient starts an interview with Infermedica API, a single Interview-Id should be generated. It’s the API client’s responsibility to generate that Interview-Id.

Format of an Interview-Id

Infermedica does not enforce any particular form, but we recommend following these rules:

The Interview-Id should be unique to a single interview. In other words, no interviews should share the same Interview-Id.
The Interview-Id should stay unchanged throughout the entirety of a single interview with the API. In other words, a single interview should be marked with a single Interview-Id from start to finish.
The Interview-Id should be random (i.e. “meaningless”) - it should not convey any business/medical knowledge nor should it be any kind of PII (patient’s ID, name, etc.). In fact - on its own, it should convey no information whatsoever.

Putting all that together - the best practice is to use some kind of UUID (opens in a new tab) generation tool to create Interview-Ids.

Example requests

Let’s assume you generated an Interview-Id using the UUID tool as follows: d083e76f-3c29-44aa-8893-587f3691c0c5

Then each call to the API should add it to the Interview-Id HTTP header.

E.g. call to the /search endpoint:

cURL

       Curl "https://api.infermedica.com/v3/search?phrase=abdominal%20pain&age.value=30&sex=male"\
     -X "GET"\
     -H "App-Id: XXXXXXXX"
     -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"\
     -H "Content-Type: application/json"\
     -H "Interview-Id:d083e76f-3c29-44aa-8893-587f3691c0c5"\
     -H "Dev-Mode: true"

and a call to the /diagnosis endpoint:

cURL

      Curl "https://api.infermedica.com/v3/diagnosis"\
     -X "POST"\
     -H "App-Id: XXXXXXXX"
     -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"\
     -H "Content-Type: application/json"\
     -H "Interview-Id:d083e76f-3c29-44aa-8893-587f3691c0c5"\
     -H "Dev-Mode: true"\
     -d '{"sex":"male", "age":{"value": 30}, "evidence":[{"id":"s_100", "choice_id":"present"}]}'

Example use of Interview-Id

1. The patient initiates an interview with an Infermedica API-based product.

2. The API client generates a new Interview-Id.

3. The interview begins. Each of the mentioned requests to the API should contain the Interview-Id HTTP header. What the exact boundaries of a single interview are is dependent on your specific use-case. Here is our example:

several calls to the /search endpoint to find chief complaints (initial symptoms).
a call to the /suggest endpoint containing all of the initial evidence found in point 1.
multiple calls to the /diagnosis endpoint, starting with the initial evidence and answers to the /suggest questions. Each call results in the user being asked a question. After which, the evidence list that is included in these calls is expanded to include the user’s answer to the previous question and a subsequent call is made, getting back another question. This process repeats until a stop condition is met.
additional calls to the recommendation endpoints such as /triage, /recommend_specialist etc.

4. The interview ends.

The Interview-Id should be stored by the client.
The Interview-Id should be “forgotten” - meaning that it should never be reused for another interview.

Basics Medical Concepts