Skip to content
Healthie API Docs

Quick Start

This guide walks you through making your first Healthie API call and covers the key things to know before you start building.

Before You Begin

Section titled “Before You Begin”

Make sure you have the following ready:

  • A Healthie account with API access — contact hello@gethealthie.com if you’re not sure whether your account has API access
  • An API key — see Authentication for how to generate one, or contact us to have one provisioned
  • A basic familiarity with GraphQL — if you’re new to it, read Queries and Mutations first (15 min)
  • A tool to send requests — the API Explorer requires no setup and is the easiest way to start (it runs against the Sandbox environment); Insomnia and Postman are good options for more advanced use

Step 1 — Choose Your Environment

Section titled “Step 1 — Choose Your Environment”

Healthie provides two separate environments. Always start in Sandbox — it’s isolated from production data.

NameURL
Sandboxhttps://staging-api.gethealthie.com/graphql
Productionhttps://api.gethealthie.com/graphql

See Environments for a full list of sandbox limitations (faxing, some integrations, etc.).

Step 2 — Authenticate

Section titled “Step 2 — Authenticate”

All requests to the Healthie API require two headers:

Authorization: Basic YOUR_API_KEY_HERE
AuthorizationSource: API

Every API request is a POST to the environment URL with these headers plus a Content-Type: application/json header.

Step 3 — Make Your First API Call

Section titled “Step 3 — Make Your First API Call”

The Healthie API is a GraphQL API. Every request — whether reading data or writing it — is a POST with a JSON body containing a query or mutation field.

What a request looks like

Section titled “What a request looks like”
{
  "query": "{ currentUser { id email first_name last_name } }"
}

This JSON body is POSTed to the API URL with the auth headers from Step 2.

Your first query

Section titled “Your first query”

The currentUser query is the simplest way to verify your API key is working. It returns the user account associated with the key.

{
  currentUser {
    id
    email
    first_name
    last_name
  }
}

What to expect back

Section titled “What to expect back”

A successful response looks like this:

{
  "data": {
    "currentUser": {
      "id": "12345",
      "email": "you@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  }
}

If authentication fails, you’ll receive an error in the errors array instead of data. See Error Handling for details.

Try it in the API Explorer

Section titled “Try it in the API Explorer”

The easiest way to run this query is the API Explorer — a built-in GraphQL IDE that lets you write and execute queries directly in the browser without any client setup. The Explorer always runs against the Sandbox environment, so it’s safe to experiment without affecting production data. Paste the query above, set your API key, and run it.

Use a GraphQL client in your code

Section titled “Use a GraphQL client in your code”

When you’re ready to call the API from your application, Healthie recommends using a GraphQL client library in your language of choice rather than building requests by hand. Clients handle request formatting, variables, and response parsing for you, which makes the whole process much easier. See the list of GraphQL clients to find one for your stack.

Step 4 — Explore Further

Section titled “Step 4 — Explore Further”

Once your first call is working, here are the most common next areas to explore:

Things to Keep in Mind

Section titled “Things to Keep in Mind”

A few patterns and gotchas that will save you time as you build:

IDs are environment-specific. Sandbox and Production are fully isolated — the same record will have a different ID in each. Never hardcode IDs; always look them up in the environment you’re targeting.

Queries read, Mutations write. The GraphQL spec separates these operations. If you’re creating, updating, or deleting data, you’re writing a mutation.

List queries are paginated. Queries that return lists will cap the number of results by default. Build pagination into any workflow that fetches lists. See Pagination.

All timestamps are UTC. Healthie stores and returns times in UTC. Handle timezone conversion in your application. See Timezones.

API keys inherit user permissions. A key takes on the role and permissions of the Healthie user account it belongs to. If an API call is failing with a permissions error, check that the associated user account has the right access.

Prefer webhooks over polling. Healthie supports Webhooks for common events (appointment created, form submitted, etc.). Using them is more efficient and reliable than polling for changes.