Untitled

Consolidate Health Connect API Quick Start Guide

This walkthrough guide takes you from “Connect health records” to your first successful API request.

It’s written so that:

• Developers can implement directly (copy/paste examples)
• Non-technical teams can understand what’s being built and why
• Teams using AI coding tools can follow a deterministic sequence with clear inputs/outputs

Before you start

Recommended: If you haven’t read the prerequisites guide on What you Need Before you Start, please do so.

You should have:

• Client ID and Client Secret from Consolidate Health
• At least one preregistered Redirect URI
• A backend endpoint capable of calling the token endpoint securely

You will be working with these base URLs:

• Authorization: https://app.consolidate.health/connect/api/v1/authorize
• Token: https://app.consolidate.health/connect/api/v1/token
• API base: https://app.consolidate.health/connect/api/v1

Step 1: Redirect the patient to the authorization endpoint

Step 2: The patient completes the Consolidate Health flow

Step 3: Handle the authorization callback

Step 4: Exchange the authorization code for tokens (backend only)

Step 5: Make your first API request

Token refresh (required for production integrations)

Access tokens expire (the current guide indicates 6 hours). Use the refresh token to obtain a new access token.

Refresh example

curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=refresh_token" \\
  --data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"

Recommended behavior:

• On 401 Unauthorized, refresh the token and retry once.
• If refresh fails, prompt the user to reconnect.

Common pitfalls and how to avoid them

Redirect URI mismatch

If the redirect_uri you send does not match exactly what was preregistered, authorization will fail. Keep a single source of truth for the redirect URI string.

State validation skipped

If you don’t validate state, you risk accepting forged callbacks. Always validate.

Token exchange attempted in frontend

This will fail due to security constraints and may surface as CORS issues. Always exchange the code on the backend.

Old authorization code

Authorization codes are time-limited. If a user restarts the flow or token exchange takes too long, restart at Step 1.

Next step

First Successful API Call

A short page focused on confirming success, understanding what the patient_id represents, and expanding from one endpoint to the rest.

Untitled