Social Services Directory API Guide
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 |
---|---|
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 Authorization
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 Community Information Exchange Hub Region URL
Environment | URL |
---|---|
Development | |
UAT | |
Production |
Â
Headers
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 |
---|---|---|
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. |
Â