Healthie User Management API Guide

Auth method: API Key (Bearer token in Authorization header)

Setup steps

1. Log in to your Healthie account.
2. Navigate to Settings > Integrations > API Keys.
3. Generate a new API key for your organization or user.
4. Include the key in all requests as: Authorization: Basic

Get current user

• Method: POST
• URL: https://api.gethealthie.com/graphql
• Watch out for: Returns the user associated with the API key used in the request.

Request example

query {
  currentUser {
    id
    first_name
    last_name
    email
    role
  }
}

Response example

{
  "data": {
    "currentUser": {
      "id": "123",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "role": "provider"
    }
  }
}

Get user by ID

• Method: POST
• URL: https://api.gethealthie.com/graphql
• Watch out for: Requires appropriate provider/admin permissions; clients cannot query other users.

Request example

query {
  user(id: "456") {
    id
    first_name
    last_name
    email
    active
  }
}

Response example

{
  "data": {
    "user": {
      "id": "456",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@example.com",
      "active": true
    }
  }
}

List users (clients)

• Method: POST
• URL: https://api.gethealthie.com/graphql
• Watch out for: Returns clients visible to the authenticated provider. Use offset for pagination.

Request example

query {
  users(offset: 0, keywords: "") {
    id
    first_name
    last_name
    email
  }
}

Response example

{
  "data": {
    "users": [
      {"id": "1", "first_name": "Alice", "last_name": "A", "email": "a@ex.com"},
      {"id": "2", "first_name": "Bob", "last_name": "B", "email": "b@ex.com"}
    ]
  }
}

Create user (client)

• Method: POST
• URL: https://api.gethealthie.com/graphql
• Watch out for: Use createClient for patient/client users; provider creation uses a separate mutation. dietitian_id assigns the client to a provider.

Request example

mutation {
  createClient(input: {
    first_name: "Jane"
    last_name: "Doe"
    email: "jane@example.com"
    dietitian_id: "789"
  }) {
    user { id email }
    messages { field message }
  }
}

Response example

{
  "data": {
    "createClient": {
      "user": {"id": "999", "email": "jane@example.com"},
      "messages": []
    }
  }
}

Update user

• Method: POST
• URL: https://api.gethealthie.com/graphql
• Watch out for: Partial updates are supported; only provided fields are changed.

Request example

mutation {
  updateClient(input: {
    id: "999"
    phone_number: "555-1234"
    timezone: "America/New_York"
  }) {
    user { id phone_number }
    messages { field message }
  }
}

Response example

{
  "data": {
    "updateClient": {
      "user": {"id": "999", "phone_number": "555-1234"},
      "messages": []
    }
  }
}

Delete user

• Method: POST
• URL: https://api.gethealthie.com/graphql
• Watch out for: Deletion may be irreversible; confirm behavior with Healthie support for HIPAA data retention requirements.

Request example

mutation {
  deleteClient(input: { id: "999" }) {
    id
    messages { field message }
  }
}

Response example

{
  "data": {
    "deleteClient": {
      "id": "999",
      "messages": []
    }
  }
}

Create provider/team member

• Method: POST
• URL: https://api.gethealthie.com/graphql
• Watch out for: Provider/staff creation uses organization membership mutations, not createClient.

Request example

mutation {
  createOrganizationMembership(input: {
    email: "provider@example.com"
    first_name: "Dr"
    last_name: "Smith"
  }) {
    organizationMembership { id }
    messages { field message }
  }
}

Response example

{
  "data": {
    "createOrganizationMembership": {
      "organizationMembership": {"id": "555"},
      "messages": []
    }
  }
}

Get organization members

• Method: POST
• URL: https://api.gethealthie.com/graphql
• Watch out for: Only accessible to organization admin-level API keys.

Request example

query {
  organizationMembers {
    id
    first_name
    last_name
    email
    role
  }
}

Response example

{
  "data": {
    "organizationMembers": [
      {"id": "10", "first_name": "Dr", "last_name": "Jones", "email": "jones@clinic.com", "role": "provider"}
    ]
  }
}

• Rate limits: Healthie does not publicly document specific rate limit thresholds or tiers in their developer docs as of the knowledge cutoff.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No publicly documented rate limits found. Contact Healthie support for enterprise-level rate limit details.

• Pagination method: offset

• Default page size: 10

• Max page size: Not documented

• Pagination pointer: offset / page

• Webhooks available: Yes

• Webhook notes: Healthie supports webhooks to notify external systems of events such as new appointments, form completions, and user changes. Webhooks are configured in the Healthie dashboard under Settings > Integrations > Webhooks.

• Alternative event strategy: Polling via GraphQL queries if webhooks are not available on a given plan.

• Webhook events: appointment.created, appointment.updated, appointment.deleted, client.created, client.updated, form_answer_group.created, billing.updated

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise (white-label)
• Endpoint: Not documented

Limitations:

• No native SCIM 2.0 endpoint documented in official Healthie developer docs.
• IdP-based provisioning (Okta, Entra, etc.) is not officially documented as supported.
• User provisioning must be done via the GraphQL API directly.

Three provisioning scenarios cover the primary lifecycle operations.

To provision a new patient, execute createClient with first_name, last_name, email, and dietitian_id;

omitting dietitian_id will cause the client to not appear in provider dashboards.

To deactivate a departing user, query by email using a keywords filter to retrieve their id, then set active: false via updateClient;

hard deletion via deleteClient is likely irreversible and may conflict with HIPAA data retention obligations, so deactivation is the safer default.

To sync organization staff, query organizationMembers to retrieve current provider accounts, use createOrganizationMembership for new staff, and subscribe to client.created and client.updated webhooks to keep an external directory current

this last step is essential for maintaining an accurate identity graph across your stack.

Provision a new patient/client

1. Authenticate with your organization API key (Authorization: Basic ).
2. Execute the createClient GraphQL mutation with required fields: first_name, last_name, email, and dietitian_id.
3. Capture the returned user.id for future reference.
4. Optionally update additional profile fields (dob, phone_number, timezone) via updateClient mutation.

Watch out for: dietitian_id is required to assign the client to a provider; without it the client may not appear in provider dashboards.

Deactivate a user when they leave

1. Query the user by email using the users query with a keywords filter to retrieve their id.
2. Execute the updateClient mutation with active: false to deactivate the account.
3. Alternatively, use deleteClient if permanent removal is required and data retention policies permit.

Watch out for: Deletion is likely irreversible and may conflict with HIPAA data retention obligations. Prefer deactivation (active: false) over deletion.

Sync organization staff/providers

1. Query organizationMembers to retrieve all current provider accounts and their IDs.
2. For new staff, execute createOrganizationMembership with email, first_name, and last_name.
3. For role or profile changes, use the appropriate update mutation with the member's id.
4. Subscribe to client.created and client.updated webhooks to keep an external directory in sync.

Watch out for: Organization member management requires an admin-level API key; provider-level keys will receive permission errors.

The primary integration trap is the client/provider mutation split: tooling that assumes a single user creation path will silently fail or misroute staff accounts into the patient namespace.

A second trap is the undocumented rate limit - pipelines that fan out bulk provisioning requests without backoff logic risk unexpected throttling with no programmatic signal to recover from. The Authorization: Basic header format (rather than Bearer) will cause silent auth failures in any HTTP client that defaults to standard Bearer token handling.

Finally, because SCIM is absent, any IdP sync must be built and maintained against the GraphQL API directly, meaning schema changes in Healthie's API surface require active monitoring and pipeline updates on your side.