Meet The Human Service Data API Protocols

Open Referral’s Human Service Data API protocols (HSDA v1.2) are ready for use!

Check out our documentation site here.

Use our live developer portal here.

Watch a recording of a live videochat walkthrough of HSDA here.

Finally (for geeks and non-geeks): read the report on this phase of our development.

And read more about this exciting new chapter below:


In our mission to make it easy to share, find, and use directory information about the health, human, and social services available to people in need, Open Referral first kicked off (back in 2014) by developing a common vocabulary to describe those services, and formatting instructions for publishing such data in bulk.

Over the years, we observed that even as HSDS gained adoption across the field, many of our stakeholders were developing their own Application Programming Interfaces (APIs) to manage resource data in real-time. This shift to APIs heralds an exciting new era for technology to support community resource referral.

However, if we are to ever realize the true potential for this technology, we must ensure that these APIs across the field can be interoperable. Such interoperability will decrease the costs of developing new technology, accelerate the pace at which effective new technologies can be shared and scaled, and ensure that users have an open set of choices so that they can best meet their particular needs.

With support from the Digital Impact program (née Markets for Good) at Stanford’s Center on Philanthropy and Civil Society, Open Referral spent much of 2017 developing the Human Services Data API Suite (HSDA): a set of open source protocols for the real-time management of resource directory data.

HSDA was developed with the technical leadership of Kin Lane, the API Evangelist, and with support from the Open Data Services Cooperative. These API protocols evolved across three iterative cycles of research, design, testing, feedback, and deliberation.

HSDA is based upon Open Referral’s Human Services Data Specification (HSDS). HSDS consists of a data vocabulary, logic model, and formatting instructions for bulk publication of resource directory data (about services, the organizations that provide them, and the locations at which they are accessed). HSDA layers real-time data management protocols upon this vocabulary.

To best address the diversity of user needs (see the synthesis of our research here), we’ve developed a core HSDA protocol that offers basic read-write functionality for the entire HSDS vocabulary, and then paired it with a set of complementary protocols (i.e. ‘microservices’) that each address specific use cases.

Here’s a diagram of how it all fits together:

These protocols are all drafted in OpenAPI, which is a standardized format for describing API operations. That means these protocols can be freely used as ‘blueprints’ for the design and deployment of new API-driven platforms – and they can also as tools to translate pre-existing APIs into this common format.

To see an instance of HSDA in action, check out the Miami Open211 developers portal.

We also provided a walkthrough of HSDA over a recorded video chat, which you can watch here:

Many thanks to Digital Impact, Lucy Bernholz and the Stanford PACS team, Kin Lane, Open Data Services Cooperative, and Clive Jones and the Alliance of Information and Referral Systems (which fiscally sponsored this project).

Stay tuned for reports from the field, where our stakeholders are already implementing HSDA to serve community resource directory information to their communities in new ways.

3 thoughts on “Meet The Human Service Data API Protocols

Leave a Reply

Your email address will not be published. Required fields are marked *