Introduction

About

Healthie offers a web and mobile platform for healthcare tech organizations to launch and scale digital services. Developer teams can use our API to build client-facing, and provider-facing, apps, leveraging Healthie’s back-end, data architecture, and sample front-ends.

For Developers & Customers

Healthie makes available the same API that our own front-end developers use to build Healthie (Healthie Help Guide Linked Here), so the functionality covers our entire platform, including client engagement, coaching, provider management, telehealth, insurance billing, EHR, and more. As a result, product and engineering teams are able to focus on the implementation of specific care models to deliver ideal client-facing experiences.

Many organizations also leverage our API to pull detailed data for reporting & analytics that spans business operations, financial performance, client engagement, and client outcomes.

Our developer support team is here to help answer questions you may have about the API. We encourage you to contact us: hello@gethealthie.com and also share your feedback & requests as you explore and utilize our API.

For Marketplace Partners

At Healthie, it’s our vision to improve access to healthcare and enable better healthcare outcomes through technology. By building partnerships across the healthcare and technology industry, our Marketplace helps to break down barriers to workflows, processes, and care.

Our Marketplace makes it easy for businesses to use software solutions together to enhance efficiency, increase revenue, and deliver patient care. Healthie partners with a wide range of technology platforms, as well as service providers, that collectively enable our customers to achieve the solutions they need for better business or client care outcomes.

If you are an independent software provider serving a mutual customer base with Healthie, you can leverage our API and sandbox access to self-build an integration with our platform.

Learn more about becoming a Marketplace Partner here or email marketplace@gethealthie.com.

GraphQL Overview

Healthie offers a GraphQL API. If you have not worked with GraphQL before, we recommend that you read Introduction to GraphQL and Queries and Mutations over at Learn about GraphQL before you begin development.

Our goal is to adhere to the latest GraphQL specification. If you do not believe that we are adhering to the spec, please contact us and we will work to make your experience better.

Operations

The GraphQL spec provides three types of operations: Queries, Mutations, and Subscriptions.

Queries

Requests to the Healthie API are all HTTP requests, so any HTTP client (cURL, Axios, Net:HTTP, etc) can be used to make API requests. However, using tools with better GraphQL support can help a lot when using Healthie's API. Here are our recommendations.

The easiest way to learn about and run your first GraphQL query is by using our API Explorer. It is a fully-fledged GraphQL IDE based on GraphiQL, providing you documentation and an easy to use interface to run queries.

As you progress beyond that, you can make queries via API tools like Insomnia or Postman.

Finally, when it comes time to write the actual code, we highly recommend using a GraphQL client, versus trying to construct the direct HTTP requests. Two examples are Apollo Client (for JS) and GraphQL-Client (for Ruby).

Example Projects

We have an open-source widget that utilizes the API on Github. That repo is a great place is to get started if you are looking for an example project that uses our API.

Developer Support

Healthie prides ourselves on our hands-on developer support, available to all API customers.

• We’re happy to answer any questions as they come up
• We can help you break down workflows and talk through how you can use the API to accomplish a specific goal
• We’re also happy to be in a Slack channel with your developers, or schedule screenshares/calls

API Concepts

Environments

Healthie offers two API environments - Sandbox and Production. Sandbox and Production are fully seperate environments, and it is not possible for Healthie to copy data between them. Please note, before hard-coding IDs into your integration, that they will be different on Sandbox and Production.

The examples in this documentation use the Sandbox environment's API URL. The URLs are as follows:

Sandbox Limitations

The sandbox environment is intended for testing and development purposes only. It is not intended for production use. Due to the nature of the environment, some of the features of the API are not available in the sandbox environment. The table below shows which features are available in the sandbox environment.

Stripe

You can test Stripe payments in the Healthie sandbox environment. You'll be prompted to add a bank account in the Healthie portal — follow the instructions and use Stripe test data for the bank info. You can use any U.S. address.

If you receive the following error when using the createBillingItem or completeCheckout mutations, you likely need to complete your setup of the test bank info: "Your destination account needs to have at least one of the following capabilities enabled: transfers, crypto_transfers, legacy_payments"

Change Healthcare: E-Labs

Change Labs is not currently available in the sandbox environment. We recommend working instead with LabOrder objects, but not with the actual Change connection. Unfortunately, this restriction comes from Change -- their developer environment does not have the ability to automatically trigger tests end-to-end, nor to provision new accounts.

You can generate LabOrder objects, which the Change integration also generates, in the staging environment via the API to help simulate an end-to-end testing experience.

ICD + CPT codes

Healthie provides a limited subset of ICD and CPT codes in the sandbox environment. We recommend building any workflows that rely on these codes in sandbox using stand-in codes as needed.

Authentication

Healthie uses API keys to allow access to the API. Each Healthie user account can have its own API key, and one user account can have multiple API keys.

Scopes

API keys are scoped to a user account, and the API key takes on the permissions and behaviors of the user account it is connected to. If you want to set up an "admin" API key for server-side actions, make sure you've granted all the appropriate permissions to the Healthie user account associated with that key. Actions done via a user's API key are considered to be done by the user.

You can generate API keys programmatically for other users. If you want to use this functionality, contact Healthie at hello@gethealthie.com and we'll set it up for the user account you specify.

Request headers

Healthie expects the API key to be included in all authenticated API requests to the server, via headers that look like the following:

Authorization: Basic YOUR_API_KEY_HERE

AuthorizationSource: API

If your data is in a shard (you will know if this is the case), you must also include the following header:

AuthorizationShard: YOUR_SHARD_AUTHORIZATION_ID

Generating API keys

You can generate an API key with the createApiKey mutation.

mutation createApiKey($name: String, $user_id: ID) {
  createApiKey(
    input: {
      name: $name # A used-defined name for the API key. Optional
      user_id: $user_id # The ID of the user to create an API key for. Required
    }
  ) {
    api_key
    api_key_object {
      created_at
      displayable_key
      id
    }
    messages {
      field
      message
    }
  }
}

Rate Limits

Healthie sets limits on how many requests can made against our API within a certain period of time. We put them in place to help ensure the stability and performance of our system. Our rate limit is currently 250 requests per second per API key and 100 sign in requests per minute per user. If you make too many requests over that period, our system will return an error message telling you that the rate limit has been exceeded.

Versioning

As per the GraphQL Best Practices, Healthie's API is not versioned. We avoid breaking changes, and old API clients will continue to work. This is possible since GraphQL only returns the data that's explicitly requested. New capabilities can be added to Healthie's API via new types and new fields on those types without creating a breaking change.

In short, one way to think of a breaking change is as such, a breaking change is one that, given no change to account data, changes the returned values of a query or mutation.

Examples of changes we would consider breaking (and so would not make):

• Removing a field
• Changing the return type of a field
• Changing an input argument default (e.g changing a query to be default unpaginated versus paginated)

Examples of changes we do not consider breaking (and so would make)

• Adding new queries and mutations
• Adding an optional new input field to an existing query or mutation
• Adding a new filter or sort_by option to an existing input field
• Adding new and updated data to Healthie-provided resource queries (e.g Insurance Plans or Icd Codes)
• Fixing an internal server error (e.g a 500)

Error Handling

As noted, our goal is to adhere to the latest GraphQL specification, including Section 7.1.2 on errors. Although the spec is transport-agnostic, our system runs over HTTP and, therefore, we strive to adhere to the latest HTTP specifications, including the semantics described in RFC 9110. As such, our API responds with the most appropriate HTTP response code where applicable.

Pagination

Many queries in Healthie's API are paginated. We use offset-based pagination. When a query takes in an offset argument, that specifies where the data returned should start. For example, our entries query has a page size of 10. if you have a list of 20 entries, and want to load all of them in, you would first do an entries query with offset of 0 and then an entries query with an offset of 10. Many queries have a corresponding "count" query (e.g entries has an entriesCount), That "count" query lets you see the total amount of data that you will need to page through.

If you send in an offset value that is too large (e.g 150 for a data set that only contains 100 objects), our API will just return an empty array.

Cursor Pagination

Healthie suggests using the new Cursor pagination instead of the previously available offset-based pagination. It is more stable, performant, and easier to use. Each query supporting Cursor pagination has an after input argument and returned objects provide a cursor field. To fetch the next page of results, use the cursor value from the last item returned in the current query.

{
  announcements(page_size: 2, should_paginate: true) {
    id
    cursor
  }
  announcementsCount
}

Consider the following query:

{
  "data": {
    "announcements": [
      {
        "id": "3",
        "cursor": "eyJrIjpbIjMiXX0="
      },
      {
        "id": "2",
        "cursor": "eyJrIjpbIjIiXX0="
      }
    ],
    "announcementsCount": 3
  }
}

Which should give a result like this:

{
  announcements(page_size: 1, should_paginate: true, after: "eyJrIjpbIjIiXX0=") {
    id
    cursor
  }
  announcementsCount
}

Now, let's take the cursor value of the last item on the list and use it in the next query:

{
  "data": {
    "announcements": [
      {
        "id": "1",
        "cursor": "eyJrIjpbIjEiXX0="
      }
    ],
    "announcementsCount": 3
  }
}

It should return the next set of result after the specified cursor.

Queries that currently support Cursor pagination:

• announcements
• api_keys
• appointment_types
• appointments
• billing_items
• comments
• conversation_memberships
• course_memberships
• courses
• cpt_codes
• customEmails
• document_viewings
• food_search
• user_package_selections

Client Mutation ID

In the schema, you will come across the field clientMutationId on all of our mutations. This is a GraphQL auto-generated field that is not used in our API. You should not send in a clientMutationId and can ignore the field.

Terminology

Due to the API's evolution over time, and the wide range of use-cases we support, there are a few terms that are used interchangeably throughout the API docs. There are also some terms that may have API objects with non-obvious names. Here is a quick glossary to help you better understand the documentation (especially the Schema mentioned below).

• Patient/Client are used interchangeably.
• Provider/Dietitian are used interchangeably.
• Support Member/Staff Member mean a member of an organization who is not a provider, and are used interchangeably.
• A "Chat Message" is the Note object in our API. A "Chart Note" is represented as a FormAnswerGroup
• An "Invoice" is a RequestedPayment
• A "Payment" is a BillingItem

Webhooks

Healthie's API offers webhooks for common events.

When the event happens, Healthie will send a HTTP POST request with the following body to a URL you provide us.

You can see an example HTTP POST body in the right-hand column.

{

"resource_id": resource_id, # The ID of the resource that was affected

"resource_id_type": resource_id_type, # The type of resource (can be 'Appointment', 'FormAnswerGroup', 'Entry', or 'Note')

"event_type": event_type # The event that occurred

}

We support different URLs for each event, as well as multiple URLs for the same event.

Retry Logic

You can choose to opt into having us retry a failed webhook if your service returns an error when we send a webhook to you. We will retry sending the webhook for up 3 days based on an exponential backoff. After retrying for up to 3 days, we will disable the webhook.

Email on Failure

If your service continues to return an error, we will send an email notification to let you know after approximately 24 hours.

Email on disable

If your service continues to return an error, we will disable the webhook after approximately 3 days.

Better URL validation

We have better validations around the URL of the service that you specify. You will be notified sooner if your URL does not validate.

Signed payloads

Overview

When you receive webhooks from our service, it is important to verify that they were indeed sent by us. This can be achieved by validating the signature in the webhook's headers. Below, we provide the steps and a code sample for verifying the signature using JavaScript.

Signature Verification Process

Each webhook request includes several headers that are used to ensure the authenticity and integrity of the request:

• Content-Type: Specifies the media type of the resource (should be application/json).
• Content-Digest: Contains a SHA-256 hash of the request payload.
• Signature-Input: Specifies the components used to construct the signature.
• Signature: Contains the actual cryptographic signature of the message that you need to verify.

The signature is computed using HMAC (Hash-Based Message Authentication Code) with SHA-256 hashing. The data string used to generate the signature is constructed using specific parts of the request, including the HTTP method, path, query, and body content.

Steps to Verify the Signature

1. Construct the Data String: Replicate the construction of the data string that was signed on the server side. This involves concatenating the HTTP method, path, query string, content digest, content type, and content length of the request.

2. Compute the HMAC: Using the same key that the server used, compute the HMAC with SHA-256 of the data string.

3. Compare the Computed HMAC with the Signature in the Request: The signature provided in the webhook's Signature header should match the HMAC you computed. If they match, the request is verified.

JavaScript Code Sample

async function getSigningKey(secretKey) {
    const encoder = new TextEncoder();
    const keyData = encoder.encode(secretKey);
    return await crypto.subtle.importKey(
        'raw',
        keyData,
        { name: 'HMAC', hash: { name: 'SHA-256' } },
        false,
        ['sign']
    );
}

function constructDataToSign({ method, path, query, headers, body }) {
    const contentDigest = headers['content-digest'].split('=')[1];
    const contentType = 'application/json';
    const contentLength = new Blob([JSON.stringify(body)]).size;
    return `${method.toLowerCase()} ${path} ${query} ${contentDigest} ${contentType} ${contentLength}`;
}

async function generateSignature(key, data) {
    const encoder = new TextEncoder();
    const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(data));
    return Array.from(new Uint8Array(signature))
        .map(byte => byte.toString(16).padStart(2, '0'))
        .join('');
}

async function verifySignature(requestData, secretKey) {
    const key = await getSigningKey(secretKey);
    const dataToSign = constructDataToSign(requestData);
    const computedSignature = await generateSignature(key, dataToSign);
    const actualSignature = requestData.headers['signature'].split('=')[1];

    return computedSignature === actualSignature;
}

// Example usage
const requestData = {
    method: 'post',
    path: '/uri/path/here',
    query: '', // any query params. leave blank if none
    body: {
        resource_id: 123123123,
        resource_id_type: 'Appointment',
        event_type: 'appointment.updated',
        changed_fields: ["pm_status_last_changed_by_id", "last_updated_by_id"]
    },
    headers: {
        'content-type': 'application/json',
        'content-digest': 'SHA-256=content-digest-from-header',
        'signature': 'sig1=signature-from-header'
    }
};

const secretKey = 'whsec_my-secret-key'; // The secret shared with you
verifySignature(requestData, secretKey)
    .then(isValid => console.log('Is the signature valid?', isValid))
    .catch(err => console.error('Error verifying signature:', err));

Thin payloads

When webhooks are sent for updates, we will include a changed_fields property to the payload we send. This property will contain a list of fields that changed during the update.

Please note: For webhooks related to a created event or deleted event, we do not send data about the event other than the resource ID and event category. We expect you to make a GraphQL API call after receiving the event, using the resource ID, to get the data you need.

Security

In addition to signing our webhooks, you can whitelist Healthie's current IP addresses as an additional security measure:

Staging / sandbox environment: 18.206.70.225 44.195.8.253

Production environment: 52.4.158.130 3.216.152.234

Please note that Healthie's IP addresses are subject to change. However, a change would be unusual and Healthie would notify your team ahead of time about the change.

Below are the webhook event types available currently:

*The appointment-related webhook events are only triggered for one-time appointments by default. If you also want to receive appointment-related events for recurring appointments, please reach out to the Healthie support team at hello@gethealthie.com and we'll turn them on for you.

Don't see a webhook for an event you want to listen to? Please reach out to us.

Examples

Say you would like to add a special external video link when patients under a particular provider book an appointment. You could:

• listen to the appointment.created webhook event
• fetch the appointment when the event is received
• if the appointment's provider is a match, use the updateAppointment mutation to update the appointment's external_videochat_url

You can find more examples how to leverage Healthie API Webhooks in the Automation Examples section.

When specific webhook events are triggered

Webhook behavior in the context of sub-organizations

If your company is using sub-organizations in Healthie, you may want certain webhook events to fire only when they are triggered by an action in a given sub-org. Here is how webhook events behave in the context of parent organizations and sub-organizations:

• If the parent org has a webhook set up, all relevant events from all sub-orgs will be sent to that endpoint
• If a sub-org has a webhook set up, only relevant events from that sub-org will be sent to that endpoint

File Uploads

Some Healthie API mutations provide support for uploading files. While it's not natively supported by the Apollo Client, it can be achieved by using third-party libraries like apollo-upload-client.

Alternatively, here's a curl command to upload the image as a base64 string:

curl --request POST \
  --url https://staging-api.gethealthie.com/graphql \
  --header 'Authorization: Basic KEYHERE' \
  --header 'AuthorizationSource: API' \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation createDocument($file: String) {\n\tcreateDocument(input: {rel_user_id: \"10\", share_with_rel: true, file_string: $file, display_name: \"example.pdf\"}) {\n\t\tdocument {\n\t\t\tid\n\t\t}\n\t}\n}\n","variables":{"file":"data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"},"operationName":"createDocument"}'

Healthie API uses the Upload type for fields that support file uploads.

For implementation details, please refer to the documentation of the GraphQL upload library of your choice.

API Deprecations

Introduction

Our API evolves over time to add new features, improve functionality, and maintain security. When certain features or practices become outdated, they will be deprecated, meaning they are scheduled to be removed or replaced by a newer alternative. Remember, deprecation does not mean immediate removal but indicates that the feature should be avoided and planned for replacement in the future.

This page is designed to provide you with the latest information about deprecated features within our API. We understand that changes to the API can impact your development process and we are committed to ensuring a smooth transition for all users.

Our API leverages the GraphQL @deprecated directive to flag deprecated fields and enum values. This feature enables you to see warnings within your development environment or GraphQL Explorer when you are using a deprecated feature.

Deprecation Policy

Our deprecation policy is designed to give developers a clear and predictable path for transitioning from old features and functionality to new ones. When a feature is deprecated:

• We will provide a minimum of 6 months notice before any deprecated feature is removed.
• We will provide migration instructions for deprecated features.

List of Deprecated Features

Below is a list of features that are currently deprecated within our GraphQL API.

String-based sort_by query arguments

• Deprecation date: November 6, 2023
• Expected removal date: August 6, 2024
• Recommendation: All API clients should use the enum-based order_by arguments.

Migration Support

If you have any questions or concerns about migrating from deprecated features, please reach out to our support team at hello@gethealthie.com.

We appreciate your understanding and cooperation as we continue to improve our GraphQL API to serve you better.

User Accounts

There are two primary types of accounts in Healthie: Patients and providers. If a user in Healthie is a patient, that means the user is not a provider and vice versa (the types are mutually exclusive). On the User type, the field is_patient signifies whether a user is a patient.

Organizations

When using the Healthie API, your company will have an organization (Organization type) and potentially sub-organizations associated with it. Every provider in Healthie is associated with one organization, but patients are not associated with an organization directly in the data model. Instead, patients are associated with one or more providers.

If a provider works for multiple organizations or sub-organizations, the provider will have multiple user accounts (one per organization).

Account uniqueness

Account uniqueness in Healthie is based on several factors:

• Every user account is associated with a namespace in Healthie. A namespace is essentially your organization's authentication space within Healthie. There can only be one patient account with the same combination of namespace, email, first_name and last_name values. This means two user accounts can have the same namespace and email if first_name and/or last_name differ between them.
• Every user account is also associated with a specific human in Healthie. A human is meant to signify an actual person using Healthie. Each human can have one or more Healthie accounts associated with them. Within a single namespace in Healthie, if multiple accounts exist with the same email, those accounts will typically be associated with the same human. The person using those accounts will be able to switch between them in the Healthie portal UI.

To avoid creating duplicate accounts in Healthie by accident, we typically recommend querying the Healthie API first to check for any users with the email specified by a person booking an appointment or signing up for your service.

Developer and owner permissions

There are no separate "developer" or "owner" account types in Healthie. Instead, these are both permission types controlled by settings on a provider account.

Developer permissions can be changed with the updateOrganizationMembership mutation using the is_developer parameter. (Every provider account in an organization has an associated OrganizationMembership.) The is_owner field on the User type shows if a given provider account is the organization owner.

API Explorer

All possible queries, mutations, and subscriptions are covered in our API Explorer. GraphQL is incredibly flexible. Using the API Explorer is a great way to see the different types of queries and mutations you can do, and the data you can get back from them.

Here is the API Explorer in action:

You will need a Sandbox API key to make queries, but you can view the live documentation without one.

Launch the Explorer

While less recommended, you can also view the schema as a website here

React SDKs

In addition to our GraphQL API, we also provide React SDKs to make it easier for developers to work with our API within their existing frontend applications and accelerate the development process.

Our SDKs provide a set of pre-built components and functions that can be integrated into your application, allowing you to access the functionality of Healthie's API with minimal setup and configuration. However, it is important to note that while the SDKs provide a simplified way to interact with our API, the developer is still responsible for providing the scaffolding and overall structure of the application.

Please note that these SDKs are designed to work with our GraphQL API only, and it is recommended to have a basic understanding of our API before using them.

Currently Healthie provides SDKs for the following capabilities:

• Chat
• Forms
• Booking & Buying (Calendar and Packages)

npm install @healthie/sdk

# or

yarn add @healthie/sdk

To get started, you can install the SDK using the following command:

For more information, please visit @healthie/sdk on npm.

Patient (Client) Management

The Patient Object

 # Some Example Fields

 "user": {
      "id": "9900",
      "first_name": "Jonas",
      "last_name": "Salk",
      "dob": "2010-10-10",
      "gender": "Male",
      "email": "jonas.salk@example.com",
      "phone_number": "555-444-2244",
      "next_appt_date": null
    }

Patients are User objects. This is the same object type that is used for providers/staff members. Due to this, The User object has an immense amount of fields, many of which are not relevant for patients. With GraphQL, you select the exact fields you want returned, so you don't need to deal with any non-relevant data.

You can view the full list of available fields here.

If you have questions about how legal_name and gender/gender_identity/sex interact with each other, We recommend reading our general help articles here and here.

Creating a Patient

Patient accounts are created in three main ways.

createClient Mutation

mutation createClient($first_name: String, 
                      $last_name: String, 
                      $email: String, 
                      $skipped_email: Boolean, 
                      $phone_number: String, 
                      $dietitian_id: String, 
                      $user_group_id: String, 
                      $dont_send_welcome: Boolean ) {
  createClient(input: { first_name: $first_name, 
                        last_name: $last_name, email: $email,
                        skipped_email: $skipped_email, 
                        phone_number: $phone_number, 
                        dietitian_id: $dietitian_id, 
                        user_group_id: $user_group_id, 
                        dont_send_welcome: $dont_send_welcome  }) {
    user {
      id
    }
    messages {
      field
      message
    }
  }
}

The createClient mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here. We will go over some of them below.

Sending a welcome email with signup_token

After creating a client with the createClient mutation, you may want to send your own welcome email to the client with the signup_token to allow them to set a password and activate their account. You can obtain the signup_token from the set_password_link field on the User object, by querying the client account with the user query.

Patient signUp Mutation

mutation signUp($timezone: String, $first_name: String, $last_name: String, $email: String, $password: String, $phone_number: String, $invite_code: String, $provider_type: String, $role: String, $dietitian_id: String) {
  signUp(
    input: {
      first_name: $first_name,
      last_name: $last_name,
      email: $email,
      password: $password,
      phone_number: $phone_number,
      invite_code: $invite_code,
      role: $role,
      dietitian_id: $dietitian_id,
      timezone: $timezone,
       }
      ) {
      user {
          id
        }
      messages {
        field
        message
      }
    }
}

The signUp mutation is called unauthenticated.

You can view a full list of potential inputs here. We will go over the inputs relevant for new patients below.

completeCheckout Mutation

The completeCheckout mutation is used for a patient to book an appointment, or make a payment. It creates a new patient if the following conditions are present

• The mutation is called unauthenticated
• The given email does not exist on another patient in the provider's account

We will go over this mutation in more depth in the Scheduling and Payments sections.

Retrieving a Patient

query getUser($id: ID) {
  user(id: $id) {
  id
  first_name
  last_name
  dob
  gender
  email
  phone_number
  next_appt_date
  }
}

Retrieving a specific patient's information is done via the user query.

Updating a Patient

Patient account information is updated in two main ways.

updateClient Mutation

mutation updateClient(
    $id: ID,
    $first_name: String,
    $last_name: String,
    $legal_name: String,
    $email: String,
  ) {
  updateClient(input:
    {
      id: $id,
      first_name: $first_name,
      last_name: $last_name,
      legal_name: $legal_name,
      email: $email,
    }) {
    user {
      id
      first_name
      last_name
      legal_name
      email
      }
    messages {
      field
      message
    }
  }
}

The updateClient mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

We will go over some of the required and less clear ones below.

The inputs that trigger emails/reminders (resend_welcome through requested_form_completion_id) take precendece over other demographic updates you are trying to make to the patient record. For example, if you send in a new first_name and also resend_welcome, the invite email will be sent, but the patient's name will not be updated.

bulkUpdateClients Mutation

mutation bulkUpdateClients($ids: [ID!], $active_status: Boolean) {
  bulkUpdateClients(input: { ids: $ids, active_status: $active_status } ) {
    users {
      id
    }
    messages {
      field
      message
    }
  }
}

The bulkUpdateClients mutation is called from an authenticated provider/staff account. It allows you to update multiple patients at the same time.

You can view a full list of potential inputs here.

We will go over some of the common ones below.

This mutation can only bulk update one field at a time. If user_group_id and active_status are both passed in, active_status will be ignored.

Patient updateUser Mutation

mutation updateUser(
  $first_name: String
  $legal_name: String
  $last_name: String
  $email: String
  $id: ID
) {
  updateUser(
    input: {
      first_name: $first_name
      legal_name: $legal_name
      last_name: $last_name
      email: $email
      id: $id
    }
  ) {
    user {
      id
    }
    messages {
      field
      message
    }
  }
}

The updateUser mutation is called from an authenticated patient account or (more rarely) from an authenticated provider/staff account with access to the patient.

You can view a full list of potential inputs here.

We will go over some of the required and less clear ones below.

Deleting a Patient

Patients (and User objects in general) cannot be deleted via the Healthie API. Instead, you should archive the patient using the updateClient mutation mentioned above.

List All Patients

query users(
  $offset: Int,
  $keywords: String,
  $sort_by: String,
  $active_status: String,
  $group_id: String,
  $show_all_by_default: Boolean,
  $should_paginate: Boolean,
  $provider_id: String,
  $conversation_id: ID,
  $limited_to_provider: Boolean,
) {
  usersCount(
    keywords: $keywords,
    active_status:$active_status,
    group_id: $group_id,
    conversation_id: $conversation_id,
    provider_id: $provider_id,
    limited_to_provider: $limited_to_provider
  )
  users(
    offset: $offset,
    keywords: $keywords,
    sort_by: $sort_by,
    active_status: $active_status,
    group_id: $group_id,
    conversation_id: $conversation_id,
    show_all_by_default: $show_all_by_default,
    should_paginate: $should_paginate,
    provider_id: $provider_id,
    limited_to_provider: $limited_to_provider
  ) {
      id
  }
}

A list of patients can be retrieved via the users query. This query is called from an authenticated provider/staff account.

You can view a full list of potential arguments here.

We will go over some of them below.

Patient Search

query users(
  $keywords: String
) {
  users(
    keywords: $keywords
  ) {
      id
  }
}

Patients can be searched using the keywords argument. The keywords argument can be used to search by id, first_name, legal_name, last_name, record_identifier, email, dob, and npi.

Example variables:

{
  "keywords": "John Doe 2002-01-01"
}

You can combine multiple search terms by separating them with a space. The search will return patients who match all the terms. In the provided example, the search will only return patients with the first and last names "John Doe" and a date of birth 2002-01-01.

Create Location

mutation createLocation($user_id: String, $name: String, $line1: String, $zip: String, $city: String, $state: String, $npi: String) {
  createLocation(input: {user_id: $user_id, name: $name, line1: $line1, zip: $zip, city: $city, state: $state, npi: $npi }) {
    location {
      id
      name
      line1
      zip
    }
    messages {
      field
      message
    }
  }
}

You can use the creatLocation or updateLocation mutations to create update address information for patients.

User Groups

The User Group Object

 # Some Example Fields

 "userGroup": {
      "id": "9900",
      "name": "Discovery Patients",
      "users_count": "7",
      "invite_code": "fbeb7f",
      "onboarding_flow_id": 11
    }

Patients can be organized into groups. Groups are a powerful feature in Healthie's API. You can trigger automations, automatically share content, restrict features, and more based on groups. You can read a full overview of the feature here.

Groups are UserGroup objects.

You can view the full list of available fields here.

Creating a User Group

mutation createGroup($name: String ) {
  createGroup(input: {name: $name }) {
    user_group {
      id
      name
    }
    messages {
      field
      message
    }
  }
}

User Groups are created via the createGroup mutation. The createGroup mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

We will go over them below.

Retrieving a User Group

query getUserGroup($id: ID) {
  userGroup(id: $id) {
    id
    name
    users_count
    invite_code
  }
}

Retrieving information on a a specific group is done via the userGroup query.

Updating a User Group

mutation updateUserGroup($id: ID, 
                         $name: String, 
                         $onboarding_flow_id: ID) {
  updateUserGroup(input: { id: $id, 
                           name: $name, 
                           onboarding_flow_id: $onboarding_flow_id}) {
    user_group {
      id
      name
    }
    messages {
      field
      message
    }
  }
}

User Groups are updated via the updateUserGroup mutation. The updateUserGroup mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

We will go over them below.

Deleting a User Group

mutation deleteUserGroup($id: ID!, 
                         $group_to_receive_clients: ID) {
  deleteUserGroup(input: { id: $id, 
                           group_to_receive_clients: $group_to_receive_clients }) {
    user_group {
      id
    }
    messages {
      field
      message
    }
  }
}

User Groups are deleted via the deleteUserGroup mutation. The deleteUserGroup mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

We will go over them below.

List All User Groups

query userGroups($offset: Int, $keywords: String, $sort_by: String) {
  userGroupsCount(keywords: $keywords)
  userGroups(offset: $offset, keywords: $keywords, sort_by: $sort_by, should_paginate: true) {
    id
    name
    users_count
  }
}

A list of groups can be retrieved via the userGroups query. This query is called from an authenticated provider/staff account.

You can view a full list of potential arguments here.

We will go over some of them below.

Tags

The User Tag Object

{
  "id": 1,
  "name": "Tag A",
  "tagged_users": [
    {
      "id": 2,
      "first_name": "John"
    }
  ],
  "user": {
    "id": 1,
    "email": "provider@example.com"
  }
}

Client Tags offer an additional way (beyond Client Groups) to assign particular attributes to clients and automate specific actions based on Tags that have been established. While clients can only be assigned to one group, clients can have an unlimited number of tags.

Tags are Tag objects.

Please note that tags are unique per provider/staff account.

Creating a Tag

mutation createTag($name: String, $taggable_user_id: ID) {
  createTag(input: {
    name: $name,
    taggable_user_id: $taggable_user_id
  }) {
    tag {
      id
      name
      tagged_users {
        id
      }
    }

    messages {
      field
      message
    }
  }
}

The createTag mutation is called from an authenticated provider/staff account.

Creating a new Tag with with the same name as another one will fail. To apply an existing Tag to other Users please check out Applying Tags to Users.

You can view a full list of potential inputs here.

Returns createTagPayload.

Updating a Tag

mutation updateTag($id: ID, $name: String) {
  updateTag(input: {
    id: $id,
    name: $name
  }) {
    tag {
      id
      name
    }

    messages {
      field
      message
    }
  }
}

Allows to change the Tag name.

You can view a full list of potential inputs here.

Returns updateTagPayload.

Deleting a Tag

mutation deleteTag($id: ID) {
  deleteTag(input: {
    id: $id
  }) {
    tag {
      id
      name
    }

    messages {
      field
      message
    }
  }
}

Use the deleteTag mutation to permanently delete a Tag. It does not delete associated Users.

You can view a full list of potential inputs here.

Returns deleteAppliedTagPayload.

List all Tags

query tags {
  tags {
    id
    name
  }
}

Display a list of all Tags for the current User's Organization.

Returns an array of Tag objects.

Applying Tags to Users

mutation applyTags($ids: [ID], $taggable_user_id: ID) {
  bulkApply(input: {
    ids: $ids,
    taggable_user_id: $taggable_user_id
  }) {
    tags {
      id
      name
    }

    messages {
      field
      message
    }
  }
}

You can apply multiple existing Tags at once to a single User by using bulkApply mutation.

The bulkApply mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

Returns bulkApplyPayload.

Removing Applied Tags

mutation removeAppliedTag($id: ID, $taggable_user_id: ID) {
  removeAppliedTag(input: {
    id: $id,
    taggable_user_id: $taggable_user_id
  }) {
    tag {
      id
      name
    }

    messages {
      field
      message
    }
  }
}

You can remove applied Tag from User by using removeAppliedTag mutation.

You can view a full list of potential inputs here.

Returns removeAppliedTagPayload.

Organization Management

The Organization Object

 # Some Example Fields

 "organization": {
      "id": "9900",
      "name": "Healthie",
      "phone_number": "555-444-2244",
      "tax_id": "123456789",
      "tax_id_type": "EIN",
      "npi": "1234567890",
      "location": {
        "city": "New York",
        "country": "US"
      }
    }

Organizations are Organization objects.

You can view the full list of available fields here.

Retrieving an Organization

query getOrganization($id: ID) {
  organization(id: $id) {
    id
    name
    location {
      city
      country
    }
  }
}

Adding an Organization Member

In order to create a new Organization Member, you should use the createOrganizationMembership mutation.

mutation createOrganizationMembership(
  $first_name: String, 
  $last_name: String, 
  $email: String, 
  $password: String,
  $title: String,
  $org_role: String,
  $send_invite_email: Boolean, 
  $phone_number: String, 
  $dont_send_welcome: Boolean,
  $organization_id: ID,
  $timezone: String
) {
  createOrganizationMembership(input: {
    first_name: $first_name, 
    last_name: $last_name,
    email: $email,
    password: $password,
    title: $title,
    org_role: $org_role,
    send_invite_email: $send_invite_email,
    phone_number: $phone_number, 
    dont_send_welcome: $dont_send_welcome,
    organization_id: $organization_id,
    timezone: $timezone
  }) {
    organizationMembership {
      user {
        id
      }
      org_role
      can_see_calendar
      can_edit_forms
    }

    messages {
      field
      message
    }
  }
}

The createOrganizationMembership mutation is called from an authenticated Super Admin account or by an Organization Member with can_add_members permission.

You can view a full list of potential inputs here.

The createOrganizationMembership mutation returns an OrganizationMembership object, which describes a list of the new member's permissions. You can view a full list of potential return properties here.

Listing Providers / Organization Members

You can retrieve a list of your organization's providers and support members using the organizationMembers query.

You can view a full list of potential inputs in our API Explorer.

query getOrganizationMembers(
    $offset: Int,
    $page_size: Int,
    $keywords: String,
    $sort_by: String,
    $licensed_in_state: String,
    $conversation_id: ID
) {
  organizationMembers(
    offset: $offset,
    page_size: $page_size,
    keywords: $keywords,
    sort_by: $sort_by,
    licensed_in_state: $licensed_in_state,
    conversation_id: $conversation_id
  ) {
    id
    first_name
    last_name
    email
    has_api_access
  }
}

Updating an Organization Membership

mutation updateOrganizationMembership(
  $first_name: String, 
  $last_name: String, 
  $email: String, 
  $password: String,
  $title: String,
  $org_role: String,
  $send_invite_email: Boolean, 
  $phone_number: String, 
  $dont_send_welcome: Boolean,
  $organization_id: ID,
  $timezone: String
) {
  updateOrganizationMembership(input: {
    first_name: $first_name, 
    last_name: $last_name,
    email: $email,
    password: $password,
    title: $title,
    org_role: $org_role,
    send_invite_email: $send_invite_email,
    phone_number: $phone_number, 
    dont_send_welcome: $dont_send_welcome,
    organization_id: $organization_id,
    timezone: $timezone
  }) {
    organizationMembership {
      user {
        id
      }
      org_role
      can_see_calendar
      can_edit_forms
    }

    messages {
      field
      message
    }
  }
}

The updateOrganizationMembership mutation shares many common inputs with createOrganizationMembership and those inputs (e.g org_role or title work the same in both places). However, the updateOrganizationMembership provides more granular control over the membership object.

The updateOrganizationMembership mutation can be called by Super Admins or Organization Members with can_edit_members permission.

You can view a full list of potential inputs here.

Additionally, the updateOrganizationMembership mutation accepts a set of Boolean input parameters that determine permissions of the Member.

Returns an updateOrganizationMembershipPayload object.

Removing an Organization Member

mutation deleteOrganizationMembership($id: ID) {
  deleteOrganizationMembership(input: { id: $id }) {
    organizationMembership {
      id
    }

    messages {
      field
      message
    }
  }
}

Organization Memberships can be deleted via the deleteOrganizationMembership mutation.

You can view a full list of potential inputs here.

The deleteOrganizationMembership mutation can be called by Super Admins only.

Returns a deleteOrganizationMembershipPayload object.

Forms

Healthie supports two types of forms:

• Form Templates (Forms)
• Onboarding Flows (Intake Flows)

For more information on the feature in general, view our help articles here.

Form Templates

Form Templates are considered public to view. All mutations can be performed only by an authenticated provider/staff account.

The Form Template Object

{
  "id": "1",
  "name": "Health History",
  "has_matrix_field": true,
  "prefill": false,
  "is_video": false,
  "use_for_charting": false,
  "use_for_program": false,
  "has_non_readonly_modules": true,
  "custom_modules": [
    // An array of CustomModule objects
  ]
}

Forms are CustomModuleForm objects.

You can view the full list of available fields here.

Listing all Forms

query formTemplates(
  $include_default_templates: Boolean
  $active_status: Boolean
  $should_paginate: Boolean
  $category: String
  $keywords: String
  $offset: Int
  $sortBy: String
) {
  customModuleForms(
    include_default_templates: $include_default_templates
    active_status: $active_status
    should_paginate: $should_paginate
    category: $category
    keywords: $keywords
    offset: $offset
    sort_by: $sortBy
  ) {
    id
    is_video
    name
    prefill
    uploaded_by_healthie_team
  }
}

A list of Form Templates can be retrieved via the customModuleForms query. This query is considered public.

You can view a full list of potential arguments here.

We will go over some of them below.

Returns an array of CustomModuleForm objects.

Retrieving a Form

query form($id: ID) {
  customModuleForm(id: $id) {
    id
    has_matrix_field
    has_non_readonly_modules
    is_video
    name
    prefill
    use_for_charting
    use_for_program

    custom_modules {
      id
      hipaa_name
      mod_type
      options
      # ...
    }
  }
}

Retrieving a specific Form Template is done via the customModuleForm query. This query is considered public.

The customModuleForm query accepts the following arguments:

Returns a CustomModuleForm object.

Creating a Form

mutation createCustomModuleForm(
  $name: String,
  $use_for_charting: Boolean,
  $use_for_program: Boolean
) {
  createCustomModuleForm(input: {
    name: $name,
    use_for_charting: $use_for_charting,
    use_for_program: $use_for_program,
  }) {
    customModuleForm {
      id
    }
    messages {
      field
      message
    }
  }
}

The createCustomModuleForm mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

Returns createCustomModuleFormPayload.

Updating a Form

mutation updateCustomModuleForm(
  $id: ID,
  $name: String,
  $is_archived: Boolean
) {
  updateCustomModuleForm(input: {
    id: $id,
    name: $name,
    is_archived: $is_archived
  }) {
    customModuleForm {
      id
    }
    messages {
      field
      message
    }
  }
}

The updateCustomModuleForm mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

Returns updateCustomModuleFormPayload.

Deleting a Form

mutation deleteCustomModuleForm(
  $id: ID
) {
  deleteCustomModuleForm(input: {
    id: $id
  }) {
    customModuleForm {
      id
    }
    messages {
      field
      message
    }
  }
}

The deleteCustomModuleForm mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

Returns updateCustomModuleFormPayload.

Copying a Form

mutation copyCustomModuleForm(
  $id: ID,
  $id_list: String,
  $user_id: String
) {
  copyCustomModuleForm(input: {
    id: $id,
    id_list: $id_list,
    user_id: $user_id
  }) {
    customModuleForm {
      id
    }
    messages {
      field
      message
    }
  }
}

You can clone a Form Template by using the copyCustomModuleForm mutation.

The full input definition can be found here.

Returns copyCustomModuleFormPayload.

Sharing a Form

mutation shareCustomModuleForm(
  $id: ID,
  $form_share_recipient: String
) {
  shareCustomModuleForm(input: {
    id: $id,
    form_share_recipient: $form_share_recipient
  }) {
    customModuleForm {
      id
    }
    messages {
      field
      message
    }
  }
}

You can share a Form with another Healthie member. The recipient needs to be specified with an email address. They will receive their own independent copy of the form.

This mutation will trigger a notification email to the recipient.

You can clone a Form Template by using the shareCustomModuleForm mutation.

The full input definition can be found here.

Returns shareCustomModuleFormPayload.

Onboarding Flows

The Onboarding Flow Object

{
  "id": "1",
  "name": "Intake flow",
  "has_forms_after_welcome": true,
  "is_multiple_providers": true,
  "onboarding_items": [
    // an array of OnboardingItem documents
  ]
}

Onboarding Flows are OnboardingFlow objects. Onboarding Flows can be associated with zero or more User Groups.

Onboarding Flows consist of OnboardingItem documents.

You can view the full list of available fields here.

Listing Onboarding Flows

query onboardingFlows(
  $offset: Int,
  $keywords: String,
  $sort_by: String,
  $should_paginate: Boolean
) {
  onboardingFlows(
    offset: $offset,
    keywords: $keywords,
    sort_by: $sort_by,
    should_paginate: $should_paginate
  ) {
    id
    name
    is_multiple_providers
    has_forms_after_welcome
  }
}

A list of Onboarding Flows can be retrieved via the onboardingFlows query. This query is available to authenticated provider/staff accounts.

You can view a full list of potential arguments here.

We will go over some of them below.

Returns an array of OnboardingFlow objects.

Retrieving a Flow

query onboardingFlow(
  $id: ID,
  $user_id: ID
) {
  onboardingFlow(
    id: $id,
    user_id: $user_id
  ) {
    id
    name
    is_multiple_providers
    has_forms_after_welcome
  }
}

Retrieving a specific Onboarding Flow is done via the onboardingFlow query. This can be done either via the ID of the Flow or for a specific Patient.

You can view a full list of all potential arguments here.

Returns an OnboardingFlow object.

Creating a Flow

mutation createOnboardingFlow(
  $name: String,
  $groups_to_use_onboarding_flow: String
) {
  createOnboardingFlow(input: {
    name: $name,
    groups_to_use_onboarding_flow: $groups_to_use_onboarding_flow
  }) {
    onboardingFlow {
      id
    }
    messages {
      field
      message
    }
  }
}

The createOnboardingFlow mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

Returns createOnboardingFlowPayload.

Updating a Flow

mutation updateOnboardingFlow(
  $id: ID,
  $name: String,
  $groups_to_use_onboarding_flow: String
) {
  updateOnboardingFlow(input: {
    id: $id,
    name: $name,
    groups_to_use_onboarding_flow: $groups_to_use_onboarding_flow
  }) {
    onboardingFlow {
      id
    }
    messages {
      field
      message
    }
  }
}

Onboarding Flows are deleted via the updateOnboardingFlow mutation. The updateOnboardingFlow mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

Returns updateOnboardingFlowPayload.

Deleting a Flow

mutation deleteOnboardingFlow(
  $id: ID,
  $flow_to_receive_groups: ID
) {
  deleteOnboardingFlow(input: {
    id: $id,
    name: $name,
    flow_to_receive_groups: $flow_to_receive_groups
  }) {
    onboardingFlow {
      id
    }
    messages {
      field
      message
    }
  }
}

Onboarding Flows are deleted via the deleteOnboardingFlow mutation. The deleteOnboardingFlow mutation is called from an authenticated provider/staff account.

When deleting an Onboarding Flow, you can automatically reassign the User Groups to another Flow by using the flow_to_receive_groups argument.

You can view a full list of potential inputs here.

Returns deleteOnboardingFlowPayload.

Onboarding Items

Onboarding Items are used to associate Forms with Intake Flows.

The Onboarding Item Object

{
  "id": "1980",
  "item_type": "Insurance Form",
  "display_name": "Insurance Form",
  "is_skippable": true,
  "onboarding_flow": {
    "id": "170"
  }
}

Onboarding Items are OnboardingItem objects.

You can view the full list of available fields here.

Retrieving an Onboarding Item

query getOnboardingItem($id: ID) {
  onboardingItem(id: $id) {
    id
    item_type
    display_name
    is_skippable
    onboarding_flow {
      id
    }
  }
}

Retrieving a specific Onboarding Item is done via the onboardingItem query. This query is considered public.

Returns an OnboardingItem object.

Creating an Onboarding Item

mutation createOnboardingItem(
  $onboarding_flow_id: String,
  $item_type: String,
  $is_skippable: Boolean
) {
  createOnboardingItem(input: {
    onboarding_flow_id: $onboarding_flow_id,
    item_type: $item_type,
    is_skippable: $is_skippable
  }) {
    onboardingItem {
      id
    }

    messages {
      field
      message
    }
  }
}

Onboarding Items are created via the createOnboardingItem mutation. This mutation is called from an authenticated account.

You can view a full list of potential inputs here.

Returns a createOnboardingItemPayload object.

Updating an Onboarding Item

mutation updateOnboardingItem(
  $id: ID,
  $onboarding_flow_id: String,
  $item_type: String,
  $item_id: String,
  $is_skippable: Boolean,
  $row_order: Int
) {
  updateOnboardingItem(input: {
    id: $id,
    onboarding_flow_id: $onboarding_flow_id,
    item_type: $item_type,
    item_id: $item_id,
    is_skippable: $is_skippable,
    row_order: $row_order
  }) {
    onboardingItem {
      id
    }

    messages {
      field
      message
    }
  }
}

Onboarding Items are updated via the updateOnboardingItem mutation. This mutation is called from an authenticated account.

You can view a full list of potential inputs here.

Returns an updateOnboardingItemPayload object.

Deleting an Onboarding Item

Onboarding Items can be deleted via the deleteOnboardingItem mutation.

You can view a full list of potential inputs here.

mutation deleteOnboardingItem($id: ID) {
  deleteOnboardingItem(input: { id: $id }) {
    onboardingItem {
      id
    }

    messages {
      field
      message
    }
  }
}

The deleteOnboardingItem mutation is called from an authenticated provider/staff account.

Returns a deleteOnboardingItemPayload object.

Listing Available Item Types

query getAvailableItemTypes(
  $onboarding_flow_id: String
) {
  availableItemTypes(
    onboarding_flow_id: $onboarding_flow_id
  )
}

This query returns a serialized JSON string containing a list of available types. Each type object has an id and name field, for example: {"id":"1","name":"Financial Agreement"}.

Listing Unassociated Completed Onboarding Items

query getUnassociatedCompletedOnboardingItems(
  $user_id: String
) {
  unassociatedCompletedOnboardingItems(
    user_id: $user_id
  ) {
    id
    item_type
    item_id
    onboarding_item_id
    skipped
    user {
      id
    }
  }
}

The unassociatedCompletedOnboardingItems query returns a list of user completed Onboarding Items, that are not part of the User's current flow.

Returns a CompletedOnboardingItem object.

Creating a Completed Onboarding Item

mutation createCompletedOnboardingItem(
  $onboarding_item_id: ID,
  $user_id: ID,
  $skipped: Boolean
) {
  createCompletedOnboardingItem(input: {
    onboarding_item_id: $onboarding_item_id,
    user_id: $user_id,
    skipped: $skipped
  }) {
    completed_onboarding_item {
      id
    }
  }
}

To mark an Onboarding Item completed by a User, use the createCompletedOnboardingItem mutation.

You can view a full list of potential inputs here.

Returns a createCompletedOnboardingItemPayload object.

Form Completion Requests

Form Completion Request Object

{
  "id": 1,
  "custom_module_form": {
    "id": 1
  },
  "item_type": "cmf",
  "recipient": {
    "id": 200,
    "email": "patient@example.com"
  },
  "form_answer_group": {
    // FormAnswerGroup object
  },
  "sender": {
    "id": 1
  },
  "status": "Open"
}

When you want to send Patient a Form to complete, you create a Form Completion Request.

Within the API, Form Completion Requests are known as RequestedFormCompletion objects.

Listing all Form Completion Requests

query requestedFormCompletions(
  $userId: ID,
  $keywords: String,
  $status: String
) {
  requestedFormCompletions(
    user_id: $userId,
    keywords: $keywords,
    status: $status
  ) {
    id
    item_type
  }
}

A list of Form Completion Requests can be retrieved via the requestedFormCompletions query. This query is available to authenticated provider/staff accounts.

You can view a full list of potential arguments here.

We will go over some of them below.

Returns an array of RequestedFormCompletion objects.

Creating a Form Completion Request

mutation createRequestedFormCompletion(
    $recipient_ids: String,
    $form: String,
    $is_recurring: Boolean,
    $frequency: String,
    $period: String,
    $minute: String,
    $hour: String,
    $weekday: String,
    $monthday: String,
    $recurrence_ends: Boolean,
    $ends_on: String
) {
  createRequestedFormCompletion(input: {
    recipient_ids: $recipient_ids,
    form: $form,
    is_recurring: $is_recurring,
    frequency: $frequency,
    period: $period,
    minute: $minute,
    hour: $hour,
    weekday: $weekday,
    monthday: $monthday,
    recurrence_ends: $recurrence_ends,
    ends_on: $ends_on
  }) {
    requestedFormCompletion {
      id
    }

    messages {
      field
      message
    }
  } 
}

The createRequestedFormCompletion mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

Returns createRequestedFormPayload.

Deleting a Form Completion Request

mutation deleteRequestedFormCompletion(
  $id: ID,
  $recurringFormId: ID
) {
  deleteRequestedFormCompletion(input: {
    id: $id,
    recurringFormId: $recurringFormId
  }) {
    requestedFormCompletion {
      id
    }

    messages {
      field
      message
    }
  }
}

The deleteRequestedFormCompletion mutation is called from an authenticated provider/staff account.

You can view a full list of potential inputs here.

Returns deleteRequestedFormPayload.

Creating a Filled Out Form (e.g a chart note, or intake form)

mutation createFormAnswerGroup(
  # Should almost always true
  $finished: Boolean,
  # ID of the custom_module_form (e.g "100")
  $custom_module_form_id: String,
  # ID of the patient (e.g "61")
  $user_id: String,
  # e.g [{custom_module_id: "1", answer: "foo", user_id: "61"}, {custom_module_id: "2", answer: "bar", user_id: "61"}]
  $form_answers: [FormAnswerInput!]!
) {
  createFormAnswerGroup(
    input: {
      finished: $finished,
      custom_module_form_id: $custom_module_form_id,
      user_id: $user_id,
      form_answers: $form_answers,
    }
  ) {
    form_answer_group {
      id
    }
    messages {
      field
      message
    }
  }
}

In the Healthie API, a filled-out form is known as a FormAnswerGroup. The most important fields when creating a FormAnswerGroup are user_id, custom_module_form_id, finished, form_answers. Let's go over each one.

user_id is the ID of the patient who the form is on. When you create a FormAnswerGroup for a patient, that will be visible on the patient's chart.

custom_module_form_id is the ID of the template (known as a CustomModuleForm) that the FormAnswerGroup completes. All filled-out forms need to be backed by a CustomModuleForm. These are the templates that you can create, view, and edit in the Form Builder in Healthie.

finished is a Boolean value. This needs to be passed in as true for the form to be visible in the patient's chart and when you query for formAnswerGroups. If you do not pass in finished (or pass it in as false), you will need to query the formAnswerGroup by its ID.

form_answers is an array containing all the individual answers. Each submitted form answer needs to have a custom_module_id, user_id, and an answer. The user_id should match the user_id of the FormAnswerGroup. The custom_module_id should be the ID of the question (known as a CustomModule) that is being answered. The answer (as the name suggests) is the answer to the question.

Those fields are used in a createFormAnswerGroup mutation to create the filled-out form. Please see the right sidebar for an example.

This mutation triggers a form_answer_group.created webhook event.

Querying Filled Out Forms

query formAnswerGroups(
  $date: String, # e.g "2021-10-29"
  $custom_module_form_id: ID, # e.g "11"
  ) {
  formAnswerGroups(
    date: $date,
    custom_module_form_id: $custom_module_form_id,
    ) {
    id
    name
    created_at
    form_answers {
      label
      displayed_answer
      id
      custom_module {
        required
        id
        mod_type
        label
      }
    }
  }
}

To retrieve filled out forms, you can use the formAnswerGroups query. You can view all the argument options here but lets go over some of the most important ones below.

filler_id is the ID of the user who filled out the form. For example, you can use this argument to see all forms filled out by a given provider.

user_id is the ID of the patient whose chart the filled out form is in.

custom_module_form_id is the ID of the form template that was filled out. This can be helpful to use to see all filled out answers for a specific template (e.g you want to see all filled out "Health History" forms)

date refers to the date the form was filled out (or the date of service in the case of chart notes).

On the right, you can find an example of a simple query that returns filled out form data for a given form template and day.

Chat

For more information on the feature in general, view our help articles here.

Chat Objects

 # Some example fields for a conversation.

{
  "conversation": {
    "id": "9900",
    "conversation_memberships_count": "2",
    "name": "Quick Question",
    "includes_multiple_clients": false,
    "owner": {
      "id": "11",
      "full_name": "Jeff Smith"
    },
    "notes": [
      {
        "user_id": "123451",
        "content": "<p>Hey</p>"
      },
      {
        "user_id": "123451",
        "content": "<p>Example message</p>"
      }
    ]
  }
}