About Open Referral

How is Open Referral organized?

The Open Referral Initiative is an open community of practice, which means that our documentation and artifacts are freely accessible and adaptable by any participant (assuming they abide by our principles and values). Our network is open to anyone. Anyone can start a ‘pilot project’; in some cases, we develop semi-formal or formal partnerships in these pilot projects. Local pilots are usually where new tools, ideas, and practices are developed, tested, and evaluated before being ‘scaled’ through the Initiative itself. 

You can see our initial governance model here. You can see our template for the process and structure of our Pilot Projects here.

Our Community Forum (a Google Group) is the official channel for updates and occasional discussion. We also host occasional Assemblies (see archived videochats here) and convene in semi-formal workshops. Our Slack is where we chat. Our document archive is publicly accessible on Google Drive.

Shouldn’t we have a Yelp for Social Services? Why aren’t you trying to build that?

Lots of people are trying to build Yelp-type applications for social services. That’s not Open Referral’s role. There’s a range of reasons why:

First, information about human services is a lot more complex, variable, and sensitive than restaurant data – and unlike restaurateurs, many human service providers might not see the benefit of being listed in a Yelp for Social Services. This is a problem that simply doesn’t correspond with conventional supply-and-demand market dynamics that make Yelp possible.

Second, we want this information available in many channels and applications – including Yelp itself! Plus Foursquare, Google Places, Facebook, etc! Yet even these wouldn’t meet the needs of every user in every situation. Resource directory data should be itself a public good, freely ‘remixable’ by anyone, not trapped within any one company’s interface.

There are a range of other reasons why we don’t think this problem has one simple ‘Yelp for Social Services’ answer. Check out this talk for more insights, and email [email protected] to discuss further.

Have you seen that XKCD cartoon about Universal Standards? Aren’t standards futile?

Why yes we have seen that cartoon, many times, thanks, but no, the cartoon doesn’t show that efforts to develop standards are futile. To the contrary! We encourage skeptics of standards to take a closer read. The XKCD cartoon identifies a collective action problem, in which competitive efforts to solve the problem by competing against all other standards are doomed to fail. Collective action problems can be solved, however, by cooperation! If a new standard is designed to enable interoperability among other standards – voila!

Open Referral takes this cooperative approach. It may be less sexy, but it’s more effective. The Human Service Data Specification and API protocols are designed to enable data interchange among different ‘data languages.’ We don’t have to solve everyone’s use case! We just make it easier for different actors using systems with different standards to cooperate across these boundaries. Instead of one standard that ‘beats’ them all, there’s now one standard that enables cooperation across them all.

Can I load my data into Open Referral? Can I get data from Open Referral?

No, Open Referral is not a database or a platform. We help other organizations evolve their resource databases into open platforms. You cannot load data into Open Referral; you can use our documentation and tooling to transform your data into a standard format and deploy your own platform!

Is this really such a hard problem? Can’t AI/ML/blockchain/magic just take care of it?

Many of us, at one point or another, were hopeful that technology would provide quick fixes to systemic problems. Those hopes haven’t panned out. It turns out that some problems are so tricky that they can only really be fixed by lots of people working together over time.

To be more specific, the root of the community resource directory problem lies in an array of perverse incentives and disincentives across the health, human, and social service sectors. For instance, many providers of health, human, and social services just don’t have strong incentives to be found by more clients! This means their information just might not be out there on the internet – not in a sufficiently detailed and up-to-date form that technical wizardry like web scrapers and chatbots might need to generate reliable results. Ultimately, if we want to have reliable information about these services over time, human beings need to talk to each other. Open Referral is working to make sure that technology can facilitate and enhance these human interactions – rather than pretend like we can eliminate the need for it, which might ultimately get in the way or even cause harm.

Is Open Referral a Community Information Exchange?

We are not! The idea of a Community Information Exchange sounds great, but as we understand it, a CIE is infrastructure that facilitates the exchange of clients’ personal information among health and human service providers. This is outside of our scope: Open Referral focuses specifically on information about service providers themselves – public information about organizations, not sensitive private information about people.

That said, we do have opinions about how communities might go about designing the process of Community Information Exchange infrastructure development. Feel free to reach out and talk about it!

Will Open Referral work with this or that resource referral platform that some organizations in our community are using?

Potentially yes! As an open standards and infrastructure initiative, Open Referral is platform-agnostic. We want to see a world in which there are many platforms that can all interoperate, so that people and organizations in communities can effectively and responsibly interact with each other across organizational and technological boundaries. If there’s a platform in your community, they might already use Open Referral to publish or consume resource data from other partners. If they don’t, maybe they should 🙂 

Reach out to explore more opportunities.

How are decisions made?

When it comes to making decisions for the Initiative as a whole, simple rule of thumb is rough consensus and running code. We do things that demonstrably work, and to which none of our community members strongly object.

That said, because this is a complex problem (involving private and public sectors; spanning local, state, and federal boundaries, with many layers of technology that are rapidly changing) our approach to discovering solutions should also be complex. So the Open Referral Initiative entails various levels at which different kinds of decisions are being made by different kinds of participants. (One way to describe this is ‘polycentricity’read more about what we mean by that here.) We approach this challenge in an agile way. Rather than try to figure everything out up front, we instead work with stakeholders to identify specific steps that are worth taking in and of themselves, and which incrementally move us in the direction we want to go. We do some things, learn from them, and do more things.

This is driven by a kind of network-oriented ‘advice process’: before we do things, we ask those who will be impacted by a given decision, and those who are experts on the relevant subject, for advice. We synthesize their input and coordinate participation from a wide variety of participants, giving prerogative to our primary stakeholders (i.e. help seekers, service providers, researchers, and database administrators). Of all the feedback received from many different contributors, we assign priority to the perspectives of such lead stakeholders as represented in our pilot projects. Their feedback is submitted to Open Referral’s deputized technical stewards, who ultimately make decisions with documentation and established methods for future review.

These decision-making processes happen at the level of the overall Open Referral community, and separately at the local level of pilot projects that implement our protocols. 

At the ‘global’ level, this process entails three activities: 1) a semi-regular Assembly video call, open to all participants [see an archive of these videos here], 2) convenings of diverse stakeholders in Open Referral workshops, and 3) ad hoc ‘workgroups’ consisting of leaders with a varied set of perspectives and experiences.

How is the Open Referral Initiative funded?

There are a number of different projects weaved together through the Open Referral Initiative — each with shared goals, but different funding sources.

Sometimes the Open Referral Initiative itself receives a grant or an award for our core operations. The Open Referral Initiative is fiscally sponsored by Aspiration, a 501c3 organization that supports open source nonprofit technology projects. 

Sometimes the leadership of the initiative takes on consulting contracts through Open Referral Consulting Services, an LLC owned by Project Lead Greg Bloom. These contracts involve implementation of Open Referral’s protocols, development of related tools, and strategic facilitation of partnership development and business modeling. 

Finally, in each of our pilot localities, we are supporting our lead stakeholders (i.e., health clinics, local I&Rs, etc) in their own fundraising efforts to build their internal capacity to participate in the project.

Do you have questions about our budgeting, or ideas about how to build more capacity for our work? Reach out to [email protected]

What is the difference between Open211 and Open Referral?

Open Referral is both the name of this community of practice, and also the shorthand name of our format for community resource data (which is technically known as the Human Services Data Specification).

Open211 is a name that has been used by various people and organizations over the years. 2-1-1 Ontario has an ‘Open211’ API (the first of its kind, to our knowledge). In 2011, a Code for America fellowship team built a (now defunct) Open211 app. One of the first pilot projects for Open Referral was a group of organizations and technologists in DC who described themselves as ‘DC Open211.’ Open211 is a concept, not a formal institution.

Ohana is both the name of the Code for America fellowship team that developed a ‘first draft’ of this model, and also the name of an API (Application Programming Interface) that the Ohana team developed in San Mateo county. The Ohana API was subsequently redeveloped to serve as the initial ‘reference implementation’ of the Open Referral model. The Ohana project is now defunct. [See the Ohana API on Github here.]

Is Open Referral trying to build a national database of services?

No. We recognize that this is a local problem that should entail local solutions. That’s why we’ve developed an open data standard, which can be used by any community to find locally-appropriate methods of data sharing.

Is Open Referral ‘scraping’ 2-1-1 data?

No. Open Referral is not a database or a platform. We help other organizations evolve their resource databases into open platforms. 

For what it’s worth, we reject the idea that community resource data can or should be treated like private property. It is public information, and organizations that do business with it should be recouping the costs of maintaining it by helping other organizations add value to it, thereby capturing some of that value. It’s a much more strategic and sustainable business model than trying to sell public information. See a report from Miami Open211 about how this might work.

We do recognize that there are some resource directory projects out there that are scraping 2-1-1s data. (Some of these projects are non-profit, or all-volunteer, or even for-profit.) Scraping this data from websites is usually technically easy, and it’s legally okay too. We disapprove of this, mostly because it makes it harder to have constructive conversations about the real problem — which is that this data is not currently “open” for machine-readable re-use. We also believe that if community resource directory data were openly accessible in a machine-readable format, ‘scraping’ would be pointless. Instead, people would use such data from its source, in ways from which the source can and should benefit.

If you’re going to build a new system, who will maintain the data?

Please note that Open Referral is not developing a product. We don’t manage or hold any resource data. Our primary objective is to help communities answer the question of who should maintain resource data. We’d be glad to help you answer that question for your community.

Aren’t calling centers important for people who might not use a computer, etc?

Of course they are!

We think it’s important for this information to be accessible to a whole ecosystem of services, and for the foreseeable future, calling centers will be an essential component of a healthy ecosystem. That’s why it’s important for us to develop standards and open that can be shared throughout that ecosystem, so that there are a variety of ways to meet people’s needs.

Aren’t there already standards for service directory information?

There are existing standards among certified information-and-referral systems, but these are not designed for the open exchange of data among any system.

As a result, various organizations and institutions must all independently invest in data production and technology development. This entails many missed opportunities to share infrastructure, reuse code and data, and achieve substantial cost savings.

That said, the work of developing a ‘universal data exchange schema’ does not entail starting from scratch. Rather, it entails aligning with that which already exists.

For the first phase of Open Referral, we have identified a core set of existing standards with which our format (technically known as the Human Services Data Specification) aim to be interoperable (i.e. data can be coherently translated between these formats).

Specifically, existing standards with which Open Referral is interoperable or can become interoperable include:

What about the problem of service taxonomies?

Open Referral recognizes the existence of a diverse array of taxonomies that are used to describe types of services, organizations, and people for whom services are available. Given that such categories are inherently subjective – whereas Open Referral’s Human Services Data Specification only describes factual data – we do not prescribe a specific taxonomy.

Instead, our data format specifies a way to include any taxonomy in open data, and our API protocols offer methods for supporting multiple taxonomies for use in the same data set.

Several prominent taxonomies, such as the 2-1-1 LA Taxonomy, are prohibited from public use by intellectual property claims. This poses barriers to the accessibility of community resource data. We are committed to seek solutions that can sustainably and responsibly remove barriers to the widespread use of these important classification tools.

We’d welcome opportunities to discuss the prospect of “opening up” any given proprietary service taxonomy, as we believe such a taxonomy could be more widely used, more easily maintained, and more financially sustainable by becoming open access infrastructure. Please reach out to discuss.

What makes you think you know the right solution?

Well, we don’t yet know the right solution! We’re just not going to wait around any longer for it to be figured out. So we’re taking action. 

Essentially, we are asking: how should this data be open?

 This is a wicked problem that requires a lot of different people working together to learn about possible solutions. We believe that the best ways to address wicked problems tend to emerge from the insight and creativity of those who directly experience the problems. So our prerogative is to promote the perspectives and involvement of the true stakeholders — people who have experience seeking help from services, service providers themselves, data administrators at community-based organizations, community health researchers, etc. They’re the ones who will be best able to recognize what viable solutions really look like.

Who are the Open Referral Initiative’s ‘users’?

We’ve identified four primary types of use that are relevant to this domain. Read more here for full personas and user stories.

  • Seeking help (service users, clients, etc)
  • Providing help (service providers, i.e. anyone helping someone find information about services)
  • Administering data (anyone engaged in working with community resource data and the technical systems that use it)
  • Research (anyone trying to analyze resource data to better understand the allocation of resources in a community).

Through these distinct perspectives, we set the parameters of our research, design, and evaluation. Our format (and the associated tools) should meet all of their needs.  

Obviously, ‘help seekers’ are the ultimate stakeholders, and we should consider our work first and foremost from their perspective. Aside from this premise, we do not prioritize one stakeholder’s needs above another. 

However, we do have a specific tactical analysis that guides our work:  

We believe that the most immediate and urgent objective is to improve the ability for all kinds of service providers to make effective referrals with accurate information. One of our core hypotheses is that if/when an ‘open system’ meets the needs of the service providers in its community, those service providers will play a critical role in maintaining the accuracy of its information. 

Yet we also recognize that an increasingly common ‘use case’ is an individual searching the web themselves. Surely we want more of those self-performed searches to be effective. So, an open platform must achieve sustainability such that its information is readily findable through direct web searches. (Of course, even given success on both of those counts, we still assume there would remain a need for trained referral specialists — especially for complex situations, edge cases, etc.)

Finally, when it comes to actually adopting and using open data standards and platforms, we recognize that the most operational type of use is data administration. In other words, our format and tools must be readily usable by anyone who updates this information and manages the technology that stores and delivers it. 

As adoption of open data standards makes it easier to solve the problems of maintaining resource directory information, we anticipate that it will become a lot easier for the many different types of service providers to allocate their resources as effectively as possible toward delivering and acting upon this information.

What is a pilot project?

Open Referral is led by local pilot projects in which stakeholders take action towards establishing accessible, interoperable and reliable community resource directory data.  Pilots commit to using the Open Referral data model to exchange resource directory data among institutions — and in return, their feedback is prioritized in shaping the iteration of that model. The goals of pilot projects include demonstrating short-term value of standardized/open data exchange, while developing a plan for long-term sustainability. [Learn more.]


How can my community become a pilot project?

The formation of a pilot project probably starts with a champion who has credibility in the community and the drive to convene others around an effort to solve this problem. We expect this champion to emerge from either local government, a community anchor institution or a local referral provider. 

A fully-formed pilot project should include some combination of government, community anchor, and referral provider. It should have investment, and ideally active engagement, from local funding institutions that invest in safety net services. And a pilot should establish capacity for coordination that stands among these different institutional stakeholders — enabling each organization to identify and address its own needs, while facilitating a conversation about the collective interests in the community.

Interested in getting started in your community? Reach out to [email protected]

How can I help?

This is an open source initiative, by which we mean that anyone can freely participate in it and even adapt any of our content for their own purposes. There are lots of ways that you might be able to get involved. For example…


“I build software / do data magic / like helping open source technology projects.”

Check out our Github repo, join our Slack. Ask questions — if we don’t know the answers, help us figure them out!

If you live in the area of one of our pilot projects, you can be very helpful indeed. If you don’t live nearby a pilot project, you might be able to help start one yourself. Attend a local Code for America brigade, or some other civic technology network activity, and ask around to see if anyone else is already working on projects involving resource data.


“I am an Information-and-referral provider.”

Read through our data specification, ask any questions that come to mind — and if we don’t know the answers, help us figure them out. Make suggestions for ways to improve the spec.

Even more importantly, identify your own needs: what do you want to see happen? In a world where community resource directory data could flow among systems, where would you want to see if flow? It can be quite valuable to simply scope out an actionable ‘use case’ (some specific action that would benefit some specific set of users). 


“I work in health, human, and/or social services.”

You may be one of our most important kinds of participants. Our work only succeeds if it can help you better serve your clients. You can help us identify, scope, and implement a ‘use case,’ in which we facilitate an open data exchange that can improve the deliverability of your services and/or services in your community. Help us get there.


“I don’t code, I’m just a citizen and I want to help!”

There is LOTS of work to be done by people who don’t code! First, read through our documentation, and ask us questions about anything that’s unclear. Then, for example, you might start learning about how information about services gets collected in your community. Talk to the people who are already producing resource directories; see if they’re interested in finding new ways to produce and/or use this information. If so, write a summary of how they do their work and what they say that they need. 


NOTE: The most powerful way to help may be to find and build relationships with a group of people who have all of the above experiences. If you can form a team in your community consisting of some combination of civic technologists, service providers, with support from local government and/or funders, we will help you launch a pilot Open Referral project!

Reach out to learn more.