Documentation
Engine API
Build your solution
Interview-Id

Interview-Id

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.
BasicsMedical Concepts