Social Services Directory API Guide

1 Introduction
2 Testing out the API
3 Authorization
4 Base Rest URL
5 Headers
6 Request URLs:
7 Response

Introduction

The Social Services Directory is a repository of social services managed and curated by Michigan 211 that can be searched. The API was built on the Open Referral Specification. Here is a link to the website https://openreferral.org/ .

The API consists of four different entities that can be queried.

Entity	Description

Entity	Description
Organizations	The organization record is used to provide basic description and details about each organization delivering services. Each service should be linked to the organization responsible for its delivery. One organization may deliver many services.
Contacts	The contact table contains details of the named contacts for services and organizations. Note that in the Human Services Data Specification (HSDS) http://docs.openreferral.org/en/latest/hsds/ data package format, if an individual is the contact for multiple services, their details may be duplicated multiple times in this table, each time with a new identifier, and with the rows containing different service ids.
Services	Services are the specific types of assistance provided by organizations to a range of different constituents.
Locations	Locations are the physical or virtual locations and associated details where organizations operate. Locations may be virtual, and one organization may have many locations.

Testing out the API

A swagger page is available for testing purposes: Swagger Guide

Authorization

The authorization will contain an API key and also will use an OAuth2 access token. An API key will be provided to each client that intends to consume this API. A development key and also a separate production key will be provided. If this key is not included then an authorization error will be returned.

The process for getting an OAuth2 token can be found here https://brightstreetgroup.atlassian.net/wiki/spaces/CIEP/pages/1309802703

Scope Needed For This API

Michigan Social Services Directory - mi-cie.directory/read

Base Rest URL

The following are the URLs for this API. Please note that base url for the region you are looking for can be found here https://brightstreetgroup.atlassian.net/wiki/spaces/CIEP/pages/1310195720

Environment	URL

Environment	URL
Development	POST https://directory-dev.mi-cie.org/v1/
UAT	POST https://directory-uat.mi-cie.org/v1/
Production	POST https://directory.mi-cie.org/v1/

Headers

Header	Description

Header	Description
x-api-key	This will be a key that will provided by a community information exchange administrator.
ContentType	application/json
Authorization	This will be the access token that was retrieved using your client id and secret

Request URLs:

The following are request URLs that can be appended to valid base urls.

By Category ID:
Each ID call will return basic data for a single result.

/organizations/{organizationId}
/locations/{locationsId}
/services/{servicesId}
/contacts/{contactsId}

By Category ID complete:
Each ID complete call will return complete data for a single result.

/organizations/complete/{organizationId}
/locations/complete/{locationsId}
/services/complete/{servicesId}
/contacts/complete/{contactsId}

By Category:
Each category call will return the full data set for 1-10 results.
Parameters (All parameters are optional)
query - Allows multiple filtering options: Query Guide
page - Page of results to be returned
per_page - Number of results per page. Default is 10.
sort_by - What field to sort by
order_by - What order to sort by (asc, desc). Default is asc

/organizations
/locations
/services
/contacts

By Category Complete:
Each category complete call will return complete data for 1-10 results.
Parameters (All parameters are optional)
query - This allows multiple filtering options: Query Guide
page - Page of results returned
per_page - Number of results per page

Response

The following will be the response values from the calling of the API. The error responses will conform to the following specification. https://tools.ietf.org/html/rfc7807 .

HTTP Status Code	Description	Response Example

HTTP Status Code	Description	Response Example
200	Successful return of data.
200	Successful return of NO data
403	Request is unauthorized and will not be processed. This will happen if the x-api-key is invalid.
400	Request query parameter is malformed and will not be processed.