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

Clarity Human Services Operational API Early Access Program Info and FAQs

Explore a pre-release version of Operational API in Clarity Human Services through our Early Access Program (EAP).

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. 

The purpose of this page is to: 

  • describe the Operational API Early Access Program, and to 
  • provide general API capabilities information.

Table of Contents

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 the existing DIT XML import, HUDX-111 Pentaho reports, and existing Data Analysis/(aka Looker) APIs, the Operational API possesses these new capabilities:

  • Read and search for real-time Clarity data
    Data Analysis/(aka Looker) APIs have specified refresh intervals of at least two 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 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 quite as powerful with the DIT as it is for the Operational API. Updating in the DIT requires a newer record to be imported 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 above elements is manually via 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 at https://help.bitfocus.com/data-refresh-rate. 
  • 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 the Operational API is used for this purpose, customers should avoid making too many repetitive or complex API calls. The Operational API actually 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 that they want to quickly refresh, then 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

  1. You will need someone who can program with web APIs, as we are unable to teach that.
  2. 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).”
  3. We recommend installing the Operational API on a training Clarity instance, while developing and testing your app. Once your app is vetted by your development process, then the app can be run against a live Clarity instance with the Operational API installed.

 

Updated: 06/25/2026