Basics

The Infermedica API is available at https://api.infermedica.com/v2. All requests to the API must be made via HTTPS (we only support TLS 1.0 and onwards).

We support cross-origin resource sharing (CORS) to allow client-side code of web applications to interact with the API, but please make sure you never expose your API credentials in any client-side code of public websites.

HTTP Methods

The Infermedica API can be easily integrated with any existing HTTP client using many popular programming languages and frameworks. Our content is read-only and all of the API responses are deterministic and idempotent (meaning they will always return the same output for the same input, no matter how many times you call them). The API supports two HTTP methods: GET and POST.

  • We use GET requests to retrieve data (both lists of records, e.g./conditions, and single records, e.g. /conditions/c_1 and for simple actions (e.g. /search) that do not require any data to be sent in the request’s body.
  • We use POST requests for actions that require data to be sent in the request’s body (e.g. /diagnosis, /explain or /parse).

JSON

JSON is the only data format supported by Infermedica API. All of our endpoints return JSON objects or lists. Likewise, our POST actions expect request bodies formatted as JSON objects. Error messages are also in JSON. Requests, like responses, should be encoded in UTF-8.

Please note that we require each POST request to include the HTTP header Content-Type with its value set to application/json.

Authentication

Infermedica API uses a custom authentication mechanism. Each of your requests must include two non-standard HTTP headers: App-Id and App-Key. These parameters correspond to your unique application ID and the key you created when you signed up to our Developer Portal. You can manage your credentials on Apps page.

An example of a request could look like this (please remember to replace XXX...X with your credentials):

curl "https://api.infermedica.com/v2/info" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Models

Our default medical content is focused on primary care and is available in several languages (including English, Chinese and Russian). Moreover, we support custom translations (e.g. into Spanish and Portuguese) and even let you create customized, domain-specific medical content. Our API organizes versions of the medical content and their corresponding translations into models.

The model represents medical content (default or custom) translated into a single language.

Our primary care medical content is currently translated into four languages. Content in each language is available as a separate model:

  • infermedica-en - English model, used automatically by default
  • infermedica-zh - Chinese (Simplified) model
  • infermedica-ru - Russian model
  • infermedica-pl - Polish model

Other languages are available for selected partners. Contact us for more details.

To select a specific model you need to send its name as a custom HTTP header called Model. Example of a request using a Russian model:

curl "https://api.infermedica.com/v2/info" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Model: infermedica-ru"

Versioning

We are continually working on improving our API, its underlying inference engine and its medical content. To track and document changes we version both our API and our models. Please follow our changelog, newsletter and blog posts to make sure you're always using the most recent versions.

API versions

Each API version is assigned its own URL. Please note that API versions are backward-incompatible. The current version of the API is available at /v2.

We may introduce minor API changes without a URL change, so you need to make sure your implementations are flexible enough to handle them. Such changes and additions may include the following:

  • adding new endpoints to the API
  • adding new optional query parameters to an existing endpoint
  • adding new attributes to the JSON response of an existing endpoint
  • adding new optional attributes to the JSON request of an existing endpoint
  • changing the order of attributes of JSON responses (JSON objects are by definition sets of unordered key/value pairs)

Version /v1 is no longer supported and you should switch to /v2 as soon as possible. Please also note that we are already working on /v3. Feel free to contact us if you have any suggestions or feature requests. We will be releasing a /v3 preview shortly.

Model versions

Our models are released independently from API updates and use a timestamp as a version indicator. You should periodically query /info endpoint to check the timestamp returned as the updated_at attribute. This is especially important if you store IDs of our medical concepts (conditions, symptoms, etc.) in your application. Model updates may add, modify (or in some rare cases even delete) some of those concepts.

/info endpoint

The /info endpoint responds to GET requests by returning details of the selected model.

curl "https://api.infermedica.com/v2/info" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The returned JSON object includes attributes that describe medical content, for example:

{
  "updated_at": "2016-09-27T07:08:25Z",
  "conditions_count": 504,
  "symptoms_count": 1114,
  "risk_factors_count": 41,
  "lab_tests_count": 448
}

Requests analysis

The Infermedica API offers machine learning capabilities that can help to improve underlying statistical models or identify interesting patterns in users’ behavior. This can be especially useful if you’re using your own custom medical content. There are three optional HTTP headers that we recommend using if you want to take advantage of all features offered by Infermedica.

  • Use the HTTP header Interview-Id to group requests made during a single interview (i.e. requests made during a single conversation with a chatbot or when filling out a single intake form). Grouping requests can help to better analyze various aspects of API usage (e.g. order of questions asked, changes in condition ranking, average interview duration, or number of questions asked per interview). The Interview-Id value should be a string and you should use the same header value for all related requests. But please make sure you don’t use any of your users or patients’ personal data, as this violates our policies.
  • Use the HTTP header User-Id to keep track of the end-user who initiated the request in your application. Note that the aim of this property is to compute general statistics of users’ behavior (e.g. number of active users or number of requests per user) and not to track individual users, and our policies prohibit including any of your users’ personal details here (e.g. their e-mail or login); instead you should use hashed and anonymized identifiers. The User-Id value should be a string.
  • Use the HTTP header Dev-Mode with the value true to exclude a request from further analysis. This is useful when you make requests to the API during development of your application or when running tests; for example, all requests made through the API Reference page by default include the Dev-Mode header.
curl "https://api.infermedica.com/v2/diagnosis" \
  -X "POST" \
  -H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Interview-Id: r8oK9tf83dEtwZm9bBJU" \
  -H "User-Id: pbdpBwBZv0" \
  -H "Dev-Mode: true" \
  -d '{"sex":"male", "age":30, "evidence":[{"id":"s_100", "choice_id":"present"}]}'

Errors

API errors are returned using appropriate HTTP response codes and simple JSON objects with corresponding messages. Codes in the 4xx range indicate problems with your requests, while those in the 5xx range imply server-related issues (we make sure you don’t see those). For successfully completed requests we return a 200 HTTP response code.

There are a few possible reasons for a 4xx response code:

  • 400 - invalid JSON (e.g. extra comma), missing or invalid parameter (e.g. no age in /diagnosis request body)
  • 403 - missing or invalid credentials (App-Id or App-Key)
  • 404 - invalid URL or object not found
  • 405 - invalid HTTP method (e.g. GET instead of POST)

An example of an error response accompanying response code 400 may look like this:

{ "message": "invalid json" }