Get started

Welcome to the IMO Health Developer Portal!

The IMO Health Developer Portal offers a series of APIs that allow you to integrate our services into your apps. Our APIs enable natural language processing (NLP), problem list management, clinical data management (terminology, code, etc) and much more! This guide will walk you through the essential steps to get you from a new account to your first successful API call.

Create an account

To use our APIs, you need to register on the portal.

1. Click Log in at the top right corner of the page.
2. Click Create Account.
3. Fill out the registration form. Note that all fields are required.
4. Click Create Account at the bottom of the form.
5. After you submit the form, we will send you an email with an activation link. Click the link in the email to activate your account.

Explore our APIs

Discover our APIs and read their documentation to understand how they work:

1. Browse our API Catalog.
2. Select an API.
3. Browse the documentation: explore endpoints, parameters, and usage details.

When you decided which API(s) you would like to test, you can go ahead and create a trial app to acquire your credentials (Consumer Key and Consumer Secret).

Create a trial app

You can create apps on the Trial page. To create an app:

1. Click Trial.
2. Click Create Trial App.
3. Add a Name to the app.
4. Select the API(s) that you want to include.
5. Click Create Trial App. You are landing on the Trial page, where you can check the status of your apps.
6. Click the View icon at the end of the row.

Find your credentials on the app detail page.

Make your first API call

To interact with IMO Health APIs, you must exchange your credentials for a secure access_token. This token identifies your application and ensures you have the correct permissions. Once you have an access_token, you can perform your first request.

Authenticate

Once you have your Consumer Key and Consumer Secret, generate an authorization token:

curl -X POST 'https://api.imohealth.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
    "audience": "https://api.imohealth.com",
    "grant_type": "client_credentials"
  }'

You will receive a JSON response containing an access_token. If you did not receive an access_token, it is possible you ran into one of the following errors:

Test an endpoint

Find an endpoint you would like to try out and make your first API call. Replace <YOUR_ACCES_TOKEN> with the token generated in the previous step. In the below example, we use the /session endpoint of the Normalize API to create a session identifier:

curl -X 'GET' \
  'https://api.imohealth.com/precision/normalize/session' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'accept: application/json'

A successful request will return a 200 OK status and the following JSON body:

{
    "session_id": "85658489-309b-454e-826d-963795034f0a"
}

Best Practices

Rate Limiting

We set API rate limits across our environments to ensure fair usage and quality experience for all customers on our platform. Treat limits as maximums to avoid unnecessary load. For advice on handling 429 errors, see Handling Limits.

We proactively monitor your usage against limits and may automatically increase them based on your usage patterns. If you see a rise in rate-limited requests, contact our support team.

If you need to perform a high-traffic load test against our sandbox environment, please contact our support team at least two weeks in advance to ensure your account limit and our infrastructure are appropriately scaled.

Handling Limits

We use the standard Retry-After header to communicate the minimum seconds a client must wait until their request may be safely retried. The response header specification for rate-limited requests is included below.

curl -X GET 'https://api.imohealth.com/example/api' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_AUTHORIZATION_TOKEN>'

To ensure 429 rate limit status codes do not adversely affect your implementation, we recommend clients implement a retry mechanism with exponential back-off. Ready-made and mature implementations for retry with exponential back-off are available in most programming languages.

Next steps

You've made your first successful API call! From here, you can:

• Test the API(s) in your app, or

• Explore other APIs. Go back to the API Catalog.

Error handling

Ran into an error? Read our error handling section. For other issues, check our Support page.