The Open Referral API project

The Open Referral Initiative’s next chapter starts now!

Open Referral has helped over a dozen community organizations find new ways to share resource directory information about the health, human, and social services available to people in need. Our Human Services Data Specification provides a common ‘machine language’ that any technology can be programmed to import and/or export. This work has spurred a proliferation of ‘Application Programming Interfaces’ (APIs) — which expose machine-readable resource data for third-parties’ systems to query in real-time, so they can repurpose it in new ways.

Thanks to Markets for Good for this opportunity!So our newest mission is to establish interoperability across this new wave of resource directory APIs, so that machine-readable data about human services can be easily accessed and shared with a common protocol — regardless of technology, jurisdiction, organizational status, etc.

Toward this end, we’ve received funding from the Markets for Good program — which is now a part of the new Digital Impact initiative ( hosted by the Digital Society Lab at Stanford’s Center for Philanthropy and Civil Society!

Read Digital Impact’s announcement about the Markets for Good grantee cohort here.


It’s often hard to describe APIs to non-technical audiences. (I once wrote about creative ways to engage this challenge.)

Robot Bartender API by Ainsley Wagoner

APIs offer protocols with which applications can “get” and “put” information about, for example, human services. From Code for America’s Ohana Project to other ongoing initiatives such as Ontario 2-1-1’s Open211 initiative, multiple APIs have now been built in accordance with HSDS. Our machine-language now must evolve into this additional layer. To achieve our goal of interoperable, sustainable, and scalable resource directory information ecosystems, we need APIs across this growing field to ‘speak’ a common language — no matter what underlying programming language their own technology ‘speaks.’


With support from Digital Impact, Open Referral is now partnering with the Alliance of Information and Referral Systems to facilitate the standardization of APIs across the information-and-referral sector.

Specifically, we will develop an OpenAPI specification that can align any provider’s resource directory API — from those offered by accredited referral providers, to those offered by emerging startups, and even APIs from government data portals and other civic data infrastructures.

Kin Lane, API EvangelistThis project is launching under the leadership of Kin Lane, the API Evangelist, who has pioneered the use of standardized APIs for public good through stints at the White House Presidential Innovation Fellows, the Knight Foundation-funded Adopta Agency project, and elsewhere. (Kin has already gotten to work sketching out some ideas — check it out here and subscribe to this Github thread for more specific details.)

The OpenAPI specification development will formally begin in March.We’ll shape this working process through communication in our Google Group (join here!), our Github organization, and our Slack team (email [email protected] to request an invite).

We welcome participation from resource directory API implementers across the field, and we also have modest stipends to offer a small number of ‘subject matter experts’ who will serve as our key stakeholder representatives along the way.

Please be in touch to learn more — and thanks of you who have already worked to set this next mission up to succeed.


8 responses to “The Open Referral API project”

  1. Georgia Thomas Avatar
    Georgia Thomas

    I have been working with the underserved population for the past 15 yrs. and every time I can help folks find the services to fulfill their needs, is great. How do I go by helping some of my client who don’t even have a phone to download this app? let me know an easier way to do it with them. Please.
    God bless

    1. Greg Bloom Avatar
      Greg Bloom

      Hi Georgia – thanks for reaching out! The short answer is that Open Referral works with organizations to help them find new ways to answer your question 🙂

      So I’d like to know more about where you work, who in your community currently maintains this information, etc. Let’s be in touch – you can reach me at bloom[AT]openreferral[DOT]org

  2. Claudia Johnson Avatar
    Claudia Johnson

    You are on the right track–and the key will be to able to figure out what decisions remain as part of a human work flow (in terms of entry and receipt and processing)–and what decisions are done through the machines, computations, acceptance standards, and different analytical methods (maximize for X, minimize for Y) kind of idea. Keep pushing forward. Validation, validation, validation then will ensue–the great thing is that hopefully as you learn, the rest of us will also learn–and in the future start buidling w/some of these standards and tools (plug ins) in mind.

    Claudia Colindres Johnson

  3. […] new developers’ portal is now the baseline reference implementation for our just-launched OpenAPI specification initiative. Thanks to Kin Lane, the API Evangelist, for his ongoing leadership on the development of our API […]

  4. […] Kin Lane, the API Evangelist, who is serving as Open Referral’s deputized Technical Lead for our OpenAPI specification project. Thanks […]

  5. […] Data Specification (a common data model for structuring community resource data), the corresponding API specification, and promising pilot projects in cities across the country that aim to build the trusted, […]

  6. […] 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 […]

  7. […] their embrace of open source publishing for their style guide and standards, and partnered on a grant-funded effort to develop the initial Human Service Data API protocols. Five years ago, AIRS endorsed Open Referral’s Human Service Data Specifications as industry […]

Leave a Reply

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