For Business

Basics

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

We support cross-origin resource sharing (CORS) to allow client-side code from web applications to interact with the API. That said, you shouldn't ever expose your API credentials to any client-side code from public websites.

HTTP Methods

The Infermedica API can be easily integrated with any existing HTTP client. Our content is read-only and all of the API responses are deterministic as well as 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's 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 create when you sign up to our Developer Portal. You can manage your credentials on the Apps page.

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

cURL
curl "https://api.infermedica.com/v3/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 multiple language versions. We also support custom translations and even let you create customized, domain-specific medical content. Our API organizes versions of the medical content and their corresponding translations into models.

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

Our primary care medical content is currently available in over 20 languages. Content in each language is a separate model:

  • infermedica-ar – Arabic
  • infermedica-zh – Chinese (Simplified)
  • infermedica-cs – Czech
  • infermedica-da – Danish
  • infermedica-nl – Dutch
  • infermedica-en – English model, used automatically by default
  • infermedica-et – Estonian
  • infermedica-fr – French
  • infermedica-de – German
  • infermedica-gr – Greek
  • infermedica-it – Italian
  • infermedica-es-xl – Latin American Spanish
  • infermedica-pl – Polish
  • infermedica-pt – Portuguese
  • infermedica-pt-br – Portuguese (Brazilian)
  • infermedica-ro – Romanian
  • infermedica-ru – Russian
  • infermedica-sk – Slovak
  • infermedica-es – Spanish
  • infermedica-tr – Turkish
  • infermedica-uk – Ukrainian

Please note that only the English model is available in the free plan. 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 Ukrainian model:

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

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 /v3.

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)

Model versions

Our models are released independently from API updates and use a timestamp as a version indicator. You should periodically query /info to check that the returned timestamp has 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
curl "https://api.infermedica.com/v3/info" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

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

JSON
{
  "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 improve underlying statistical models or identify interesting patterns in users’ behavior. There are two optional HTTP headers that we recommend using if you want to take advantage of these features.

  • 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 the 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 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
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: r8oK9tf83dEtwZm9bBJU" \
  -H "Dev-Mode: true" \
  -d '{"sex":"male", "age":{"value": 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:

JSON
{ "message": "invalid json" }
QuickstartInterview-Id