Getting Started

OneRecord API provides a powerful tool for accessing a wide range of networks containing medical records, empowering developers to innovate and build the healthcare solutions of tomorrow. With a responsible and secure approach, OneRecord's goal is to offer API customers seamless and protected access to these extensive networks, enabling the creation of transformative healthcare applications and services.

Try It Now

A global sandbox API Access Token is available for users who want to try OneRecord API without needing a customer account. This global sandbox API Access Token is limited in scope, returning only synthetic patient data. However, it's an excellent way for developers to familiarize themselves with OneRecord API and its capabilities while planning their integration or waiting for their API account to be configured for the desired networks.

To start using the global sandbox API Access Token, simply navigate to the API Reference section and make calls to OneRecord API. The sandbox API Access Token is pre-populated as the Bearer token in the API Reference, making it easy to get started. If you plan to continue using the API Reference for manual testing in the future, remember to replace the global sandbox Access Token with your own organization's sandbox API Access Token when it becomes available.

Your OneRecord API Account

Your OneRecord API account follows a hierarchical structure that includes Tenants, Organizations, Devices, and Behaviors. Tenants represent the customer entity that has an interoperability relationship with OneRecord for exchanging healthcare information. Each Tenant can have one or more Organizations, which can in turn have one or more Devices. Devices are each issued an API (JWT) Access Token that allows them to make various API calls, each of which is equal to a Behavior. Your final bill is calculated based on the sum of all executed Behaviors.

To create your OneRecord API account, follow the steps outlined in this guide. By default, new accounts are configured as one Tenant with one Organization and one Device. If you require a different structure, you can declare it during the setup process or contact us for assistance.

Account Lifecycle

Your OneRecord API account will go through several phases as you move from initial evaluation to working with real patient data. The main stages are:

• Evaluation Phase:

  • Familiarize yourself with the API using the global sandbox API Access Token.
  • Fill out this web form to express interest in becoming a customer.
  • OneRecord sales team reviews your submission and, if identified as a good fit, creates your Tenant account with Organization(s) and Device(s).

• Development Phase:

  • Work on your solution using the sandbox API Access Tokens in the stage environment.
  • When ready, request to take your solution live with real PHI.
  • Complete the internal certification process with OneRecord to ensure data protection and meet necessary requirements.

• Production Phase:

  • Obtain production approval for your account in OneRecord's Pre-Production and Production environments.
  • Set up additional TLS Certificate between OneRecord and the 3rd party networks.
  • Receive live API Access Tokens for your Devices, granting your solution access to real PHI.
  • By following these phases and meeting the requirements at each stage, you'll progress from initial evaluation to successfully retrieving and consuming real medical records in your solution.

Fetching PHI Data

Retrieving medical records through OneRecord API involves different strategies depending on the network your solution connects to. There are two primary methods for obtaining patient health data: a Demographics Network Query for Commonwell and Carequality networks, and a Patient Portal Authentication (via FHIR) for querying FHIR Resources. Each method requires a specific sequence of OneRecord API calls.

At a high level, most methods share two common steps:

1. Look up the location of the patient's data within the network.
2. Retrieve the actual record using the information obtained in step 1.

The number of times step 2 is executed depends on the breadth and nature of the data needed for your solution. Keep in mind that your solution will need to consume the data, deduplicate it, and manage updates or changes.

To learn more about the specific sequence of OneRecord API calls for each method, refer to the following guides:

• Commonwell and Carequality: Demographics Network Query Guide
• FHIR Resources: Patient Portal Authentication Guide (via FHIR)

By following these guides and executing the required API calls, your solution can securely and reliably access patient health data through OneRecord API.

Authentication

Authentication with OneRecord API is a crucial part of the integration process. Each API Access Token contains cryptographic information about your API account and the environment in which you are using OneRecord API. To authenticate with OneRecord API, you must supply an API Access Token with every call to Directory Service or Integrator Service. The key is included as the Bearer token in the Authorization request header.

By providing this API Access Token, OneRecord API can identify the specific Device within your account being used. Each Device has distinct permissions to access resources across networks, configured during the onboarding process of your OneRecord account.

📘

Note

patient authentication is also required separately for each network. For more details on patient authentication, refer to the respective Integration Guides.