Skip to content
  • There are no suggestions because the search field is empty.

Clarity Human Services Operational API

This article provides details on Operational API for Clarity Human Services.

Table of Contents

Overview

The Operational API Early Access Program (EAP) allowed customers to preview planned or future development efforts for Clarity Human Services Operational API features. The Operational API EAP is no longer adding new customers, but it is still in use. 

REST API was introduced in June 2026. 

The purpose of this page is to: 

  • provide general API capabilities information for GraphQL.
  • provide general API capabilities information for REST.

Operational API: GraphQL

The following information provides general information about the Operational API: GraphQL.

What can you do with the Operational API (GraphQL specification)

  1. Ability to query, modify, add and delete
    1. Clients - including HMIS Universal Data Elements (UDEs) and Custom Client Profile fields
    2. Households: both Profile (aka“Global”) and HMIS/Enrollment-level Households
    3. Enrollments - including custom and HMIS Program-Specific Data Elements (PSDEs)
    4. Files: Client-level Files (also can be attached to an ROI)
    5. Releases Of Information (ROI)
    6. Services (enrollment-level services only)
    7. Assessment responses: Client-level data, including custom and/or enrollment-level Assessments (the Assessment itself cannot be created with the API)
    8. Notes: Enrollment-level client notes (not client-level Notes outside an enrollment)
  2. Ability to query
    1. Projects (limited Project information, see GraphQL schema)
    2. Picklist values (if you know the name of the picklist from the Field Editor in Clarity Human Services)
    3. Screens and screens fields, including HMIS Data Element ID and name metadata
  3. There are no push notifications or “publish-subscribe” functionality yet.  All updates are currently obtained by polling.

image1-Jul-23-2024-03-00-34-2608-PM

What You Can Do with Data Analytics API (aka Looker) with REST specification

Comparison of Operational API with other existing Clarity features

Compared to the existing DIT XML import, HUDX-111 Pentaho reports, and existing Data Analysis/(aka Looker) APIs, the Operational API possesses these capabilities:

  • Read and search for real-time Clarity data
    Data Analysis (aka Looker) APIs have specified refresh intervals of at least 2 hours, but GraphQL communicates with Clarity Human Services in real time. The HUDX-111 Pentaho report is not API-accessible, but it does read real-time Clarity data, unlike the Data Analysis (aka Looker) APIs.

  • Delete or edit non-HMIS Data Standard and custom records
     With DIT CSV (manual only), and with the DIT XML API (manual as well), HMIS Data Standard elements can be deleted. However, non-HMIS Data Standard and custom records can not be deleted. Client record updates, even for non-HMIS and custom data elements, are not as powerful with the DIT as they are with the Operational API. Updating in the DIT requires importing a newer record for the update to take effect.  However, with the Operational API, record editing can modify an older record in place (directly by record ID), without requiring a new record to be added.

  • Create, delete, or edit more types of Clarity-specific data elements
    • Profile Households and Profile Household memberships (as opposed to enrollment-level households)
    • Program-level Notes
    • Releases Of Information (ROIs) with file attachments

The only other way to access the elements above is manually through the Clarity web interface.

  • Granular, not bulk, operations
    With the Operational API, the focus is on quick changes or additions to just a small set of records, as it is designed for quick interactions. The DIT is designed for bulk, periodic updates.

When to use the Data Analysis/(aka Looker) APIs versus the Operational API

The Data Analysis/(aka Looker) APIs are appropriate for: 

  • Applications where customers are only reading data (for example, for a report or dashboard), and not modifying data. The refresh rates of the Data Analysis API are listed in the Data Refresh Rate article. 
  • Large, complex queries (read-only).

The Operational API may be appropriate for:

  • Small, quick queries where the overall purpose is to update or add data.
  • Situations where a customer needs a faster refresh rate.

Note: When using the Operational API for this purpose, customers should avoid making too many repetitive or complex API calls. The Operational API uses the same servers/code as Clarity Human Services, so it competes with regular Clarity users for server resources. Because of this, large report queries are not a good fit for the Operational API.

However, if customers have a few data elements they want to refresh quickly, the Operational API may be appropriate. Bitfocus does not recommend frequent queries with the Operational API, even though this API currently only offers polling, not push notifications.


Important EAP Considerations

  • You will need someone who can program with web APIs, as we are unable to teach that.
  • Please keep in mind that the EAP specifies “Customer agrees to limit their use of EAP features and services to the use case(s) reviewed with Bitfocus and further agrees to disclose any significant changes to their intended or actual use case(s).”
  • We recommend installing the Operational API on a Clarity training instance while developing and testing your app. Once your app is vetted by your development process, it can be run against a live Clarity instance with the Operational API installed.

Operational API: REST

REST Operational API endpoints are available! These APIs provide functionality similar to that of the existing GraphQL Operational APIs. However, there are some differences, aside from RESTful protocol implementation:

  • OAuth2.1 from Auth0 has been implemented, instead of the JWT Bearer Tokens.

  • Standalone Services can now be recorded, in addition to Enrollment-based Services.

  • Endpoints have some additional filters, and there is a new Client recover endpoint for previously deleted Clients.

  • A new Open API v3 Specification (aka “Swagger file”) has been published, defining all new REST endpoints.

  • The Open API v3 Specification contains linkages to corresponding definitions within the Clarity Data Standard, so the meaning of the resources accessed via the API is unambiguous.

Note: Auth0 authentication issues only an ID token, which is configured with a 36000-second (10-hour) lifetime. But after that, each Access Token a user subsequently obtains from the Clarity server is valid for 2 hours.

For access to the REST Operational API, please contact the Bitfocus Support Team. 

 

 

Updated: 07/30/2026