Getting Started

First Successful API Call

This guide will help you confirm that your integration is working end to end. By the end of this step, you should be able to make an authenticated request to the Consolidate Health API and receive patient data. This is the first “success moment” after completing the OAuth flow.

What you should have at this point

From the previous steps, your backend should already have:

  • access_token

  • refresh_token

  • expires_in

  • patient_id

✅ Recommended:

If you do not have all four, return to the Quick Start guide and complete the token exchange step first.


Understanding the patient_id

The patient_id is returned during the token exchange and uniquely identifies the patient who authorized access.

  • Every patient data request is scoped to a patient_id

  • The same patient may have multiple EHR connections behind this ID

  • Your application should store and reuse the patient_id for future API calls

You do not need to discover or create this value yourself. It is always returned by Consolidate Health.


Making your first request

All API requests must:

  • Use HTTPS

  • Include a Bearer token in the Authorization header

  • Reference the patient_id in the URL path

Example: Fetch patient medications
curl "<https://app.consolidate.health/connect/api/v1/patients/{patient_id}/medications?limit=20>" \\
  -H "Authorization: Bearer {access_token}" \\
  -H "Accept: application/json"
curl "<https://app.consolidate.health/connect/api/v1/patients/{patient_id}/medications?limit=20>" \\
  -H "Authorization: Bearer {access_token}" \\
  -H "Accept: application/json"
curl "<https://app.consolidate.health/connect/api/v1/patients/{patient_id}/medications?limit=20>" \\
  -H "Authorization: Bearer {access_token}" \\
  -H "Accept: application/json"

Replace:

  • {patient_id} with the value returned in the token exchange

  • {access_token} with your current access token


Expected response

A successful request returns:

  • HTTP status 200 OK

  • A JSON response containing medication data

The exact shape of the response depends on the patient’s connected EHR systems. Fields are normalized across providers, but some values may be empty if a source system does not supply them.

If you receive a 200 OK response, your integration is working correctly.


Handling expired access tokens

If your access token has expired, the API will respond with:

  • HTTP status 401 Unauthorized

When this happens:

  1. Use the refresh_token to request a new access token

  2. Retry the original API request with the new token

Example: Refresh access token
curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "{client_id}:{client_secret}" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=refresh_token" \\
  --data-urlencode "refresh_token={refresh_token}"
curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "{client_id}:{client_secret}" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=refresh_token" \\
  --data-urlencode "refresh_token={refresh_token}"
curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "{client_id}:{client_secret}" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=refresh_token" \\
  --data-urlencode "refresh_token={refresh_token}"

After receiving a new access_token, retry the original request.


Verifying EHR connections

To confirm which EHR portals are connected for a patient, you can call:

curl "<https://app.consolidate.health/connect/api/v1/patients/{patient_id}/ehr-connections>" \\
  -H "Authorization: Bearer {access_token}" \\
  -H "Accept: application/json"
curl "<https://app.consolidate.health/connect/api/v1/patients/{patient_id}/ehr-connections>" \\
  -H "Authorization: Bearer {access_token}" \\
  -H "Accept: application/json"
curl "<https://app.consolidate.health/connect/api/v1/patients/{patient_id}/ehr-connections>" \\
  -H "Authorization: Bearer {access_token}" \\
  -H "Accept: application/json"

This endpoint is useful for:

  • Debugging missing data

  • Displaying connection status in your UI

  • Supporting reconnect flows


Expanding beyond the first call

Once your first request succeeds, you can call any patient data endpoint using the same pattern:

Query Parameters

All endpoints support pagination via limit and offset.

  • limit: Number of results per page (default: 20, max: 100)

  • offset: Pagination offset

Example
curl "<https://app.consolidate.health/connect/api/v1/patients/0d421a99-a7db-42a3-b3fd-c64ecaaf01c1/conditions?limit=50&offset=0>" \\\\
  -H "Authorization: Bearer ory_at_BdGxCZaRWz6cVlsj3FTz5Op8KiJhliZg2mDACXU4fs0.zPSPr2Hcw3CCpkeLeK-SQt4fVxXeudCNTqi2yPE8PMo" \\\\
  -H "Accept: application/json"
curl "<https://app.consolidate.health/connect/api/v1/patients/0d421a99-a7db-42a3-b3fd-c64ecaaf01c1/conditions?limit=50&offset=0>" \\\\
  -H "Authorization: Bearer ory_at_BdGxCZaRWz6cVlsj3FTz5Op8KiJhliZg2mDACXU4fs0.zPSPr2Hcw3CCpkeLeK-SQt4fVxXeudCNTqi2yPE8PMo" \\\\
  -H "Accept: application/json"
curl "<https://app.consolidate.health/connect/api/v1/patients/0d421a99-a7db-42a3-b3fd-c64ecaaf01c1/conditions?limit=50&offset=0>" \\\\
  -H "Authorization: Bearer ory_at_BdGxCZaRWz6cVlsj3FTz5Op8KiJhliZg2mDACXU4fs0.zPSPr2Hcw3CCpkeLeK-SQt4fVxXeudCNTqi2yPE8PMo" \\\\
  -H "Accept: application/json"


Common issues and quick checks

If your first call fails, check:

  • The Authorization header uses Bearer {access_token} exactly

  • The patient_id matches the value returned during token exchange

  • The access token has not expired

  • Your request is using HTTPS

  • You are calling the correct API base URL

Quick Start In 5 Easy Steps

Quick Start In 5 Easy Steps

Quick Start In 5 Easy Steps