API Reference
The API reference provides an OpenAPI specification that can be used as a blueprint for the design or adaptation of API platforms to provide read or read/write access to information on organizations, services, locations and the details about them. The API protocol provides most of the functionality needed for simple access and exchange of data.
Along with this reference, there is a swagger ui version of the API
The source of the specification is found on GitHub and issues can be raised in the issue tracker.
Lists
Web endpoints that return lists of entities, such as services returned by a /services endpoint must be paginated.
The header returned must include these properties:
"total_items": the total number of entities (e.g. services) returned"total_pages": the total number of pages"page_number": the number of the current page"size": the number of entities in aq page"first_page": a Boolean value indicating if this is the first page"last_page": a Boolean value indicating if this is the last page"empty": a Boolean value indicating if there is an empty result set
After the header, a lists endpoint will contain an array of its main entities (e.g. services). The array will normally contain all direct properties of each item but need not contain arrays of child entities (e.g. service contacts).
Query Parameters and Filters
Many API endpoints defined in this API reference contain query parameters allowing users to filter results by various dimensions. For example, calls to the /services endpoint can include a modified_after query parameter to only include results modified on or after the supplied value.
Query parameters are cumulative in their effect, behaving as a boolean AND where the results fulfill the conditions of all supplied query parameters. For example, the following query will produce results which match taxonomy_id=XXX AND organization_id=YYY:
/services?taxonomy_id=XXX&organization_id=YYY
All APIs wishing to comply with this specification must ensure that query parameters are cumulative in their effect.
Metadata
In HSDS each object has an optional metadata field containing a metadata object. Since an API response may contain a list of many objects — each with their own nested objects — this could result in a large quantity of metadata in the response.
It should be noted that the metadata field in each object is optional, and API implementors should consider what is an appropriate level of metadata to include in each response based on their use-case.
Endpoint details
This section contains details of each API endpoint. Each section presents an endpoint defined by the API and presents a technical reference for that endpoint including query parameters, status codes, and compliance rules for HSDS and Open Referral UK.
The / endpoint
{
"version": "3.0",
"profile": "https://path/to/profile",
"openapi_url": "https://raw.githubusercontent.com/openreferral/specification/3.0/schema/openapi.json"
}
The following compliance rules apply to this endpoint
Required by HSDS? Yes
Required by Open Referral UK? Yes
Response details
This API response will return a JSON object containing the following key/value pairs:
version(String) – HSDS version of this API.profile(URI) – The identifier for the HSDS profile used by this API. This should be a URL which resolves to a location where the information on the HSDS profile of this API may be found.openapi_url(URI) – URL of the openapi JSON file which defines this API.
The /services/{id} endpoint
- GET /services/{id}
Retrieves a fully nested service with all related data with id.
Retrieve fully nested service with all related data with id.
- Parameters
id (string) – The id of the service that the request is intended to retrieve.
- Status Codes
200 OK – A Service matching the {id}, with all related data according to the HSDS Specification for Service.
{
"id": "ac148810-d857-441c-9679-408f346de14b",
"name": "Community Counselling",
"alternate_name": "MyCity Counselling Services",
"description": "Counselling Services provided by trained professionals. Suitable for people with mental health conditions such as anxiety, depression, or eating disorders as well as people experiencing difficult life events and circumstances. ",
"url": "http://example.com/counselling",
"email": "[email protected]",
"status": "active",
"interpretation_services": "Interpretation services are available in Urdu, Polish, and Slovak",
"application_process": "If you are an NHS patient please ask your GP for a referral letter, we will then be in touch with you directly. If you are not an NHS patient you should ring our reception to arrange an appointment",
"fees_description": "Non-NHS patients are expected to pay for their counselling sessions. We charge a flat rate per hour of counselling. The current rate is \u00a350 per hour. Please see our website for up to date prices.",
"wait_time": "wait_time",
"fees": "fees_description",
"accreditations": "All of our practitioners are accredited by the BASC, UKCP, and the Professional Standards Body",
"eligibility_description": "This service is intended for all people aged 12 and over who require counselling services in the MyCity area",
"minimum_age": 12,
"maximum_age": 100,
"assured_date": "2005-01-01",
"assurer_email": "[email protected]",
"licenses": "licences",
"alert": "Following COVID-19 we have moved most of our counselling sessions online. Please contact the reception if you require further information.",
"last_modified": "2023-03-15T10:30:45.123Z",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
],
"service_areas": [
{
"id": "381c64f1-a724-4884-9c21-ac96c21cca3e",
"name": "The service is available to all residents of the MyCity area. We provide the service in our offices or via video conferencing to any who can provide evidence of their residency.",
"description": "The service is available to all residents of the MyCity area, including all postcodes starting with AB1, AB2, and AB3",
"extent": "extent",
"extent_type": "geojson",
"uri": "http://example.com"
}
],
"service_at_locations": [
{
"id": "e94c9f38-1e8f-4564-91d4-d53501ab1765",
"description": "Counselling Services provided by trained professionals in the MyCity area.",
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
],
"location": {
"id": "3a19ff88-4620-4d17-9830-ac1d859eb5d5",
"location_type": "physical",
"url": "http://example.com",
"name": "MyCity Civic Center",
"alternate_name": "Civic Center",
"description": "MyCity Civic Center is located on Main Street and contains facilities for a number of civic and community services available.",
"transportation": "MyCity Civic Center is serviced by the number 1 Bus and is a short walk from the Main Street Metro Station",
"latitude": 100,
"longitude": 101,
"external_identifier": "10092008082",
"external_identifier_type": "UPRN",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
],
"addresses": [
{
"id": "74706e55-df26-4b84-80fe-ecc30b5befb4",
"attention": "A. Persona",
"address_1": "1-30 Main Street",
"address_2": "MyVillage",
"city": "MyCity",
"region": "MyRegion",
"state_province": "MyState",
"postal_code": "ABC 1234",
"country": "US",
"address_type": "postal"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"accessibility": [
{
"id": "afcf296e-1cb2-4139-9c88-33d587d1a50b",
"description": "The building is equipped with induction loops for hearing aids. Wheelchair access is possible on all levels.",
"details": "Switch hearing aid to T-coil to access the induction loop facility.",
"url": "http://example.com"
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
]
}
}
],
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
],
"organization": {
"id": "d9d5e0f5-d3ce-4f73-9a2f-4dd0ecc6c610",
"name": "Example Organization Inc.",
"alternate_name": "Example Org",
"description": "Example Org is a non-profit organization dedicated to providing services to qualified beneficiaries",
"email": "[email protected]",
"website": "http://example.com",
"tax_status": "tax_status",
"year_incorporated": 2011,
"legal_status": "Limited Company",
"logo": "https://openreferral.org/wp-content/uploads/2018/02/OpenReferral_Logo_Green-4-1.png",
"uri": "http://example.com",
"parent_organization_id": "cd09a387-91f4-4555-94ec-e799c35344cd",
"funding": [
{
"id": "1f2df32c-bf08-4b8e-bd6f-e834014b19bc",
"source": "This service is funded partially by the MyCity local government and via grants made by charity funding bodies. We also operate a for-profit department which is used to partially cover the expense of the public service"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"locations": [
{
"id": "3a19ff88-4620-4d17-9830-ac1d859eb5d5",
"location_type": "physical",
"url": "http://example.com",
"name": "MyCity Civic Center",
"alternate_name": "Civic Center",
"description": "MyCity Civic Center is located on Main Street and contains facilities for a number of civic and community services available.",
"transportation": "MyCity Civic Center is serviced by the number 1 Bus and is a short walk from the Main Street Metro Station",
"latitude": 100,
"longitude": 101,
"external_identifier": "10092008082",
"external_identifier_type": "UPRN",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
],
"addresses": [
{
"id": "74706e55-df26-4b84-80fe-ecc30b5befb4",
"attention": "A. Persona",
"address_1": "1-30 Main Street",
"address_2": "MyVillage",
"city": "MyCity",
"region": "MyRegion",
"state_province": "MyState",
"postal_code": "ABC 1234",
"country": "US",
"address_type": "postal"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"accessibility": [
{
"id": "afcf296e-1cb2-4139-9c88-33d587d1a50b",
"description": "The building is equipped with induction loops for hearing aids. Wheelchair access is possible on all levels.",
"details": "Switch hearing aid to T-coil to access the induction loop facility.",
"url": "http://example.com"
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
]
}
],
"programs": [
{
"id": "e7ec2e57-4540-43fa-b2c7-6be5a0ef7f42",
"name": "Community Mental Health Support",
"alternate_name": "MyCity Mental Health Group",
"description": "Comprehensive Mental Health Services available to residents of MyCity including CBT and Counselling. This is not an emergency service and should not be used as an alternative to hospital and GP services."
}
],
"organization_identifiers": [
{
"id": "d4dbcebc-0802-47cb-8651-b937ac4f2f3e",
"identifier_scheme": "GB-COH",
"identifier_type": "Company number",
"identifier": "1234567"
}
]
},
"funding": [
{
"id": "1f2df32c-bf08-4b8e-bd6f-e834014b19bc",
"source": "This service is funded partially by the MyCity local government and via grants made by charity funding bodies. We also operate a for-profit department which is used to partially cover the expense of the public service"
}
],
"cost_options": [
{
"id": "1fdf4d39-3d80-484d-9f92-a8ffa08621e7",
"valid_from": "2020-01-01",
"valid_to": "2022-12-31",
"option": "Under 18s and Over 60s",
"currency": "gbp",
"amount": 35,
"amount_description": "per 1 hour session"
}
],
"program": {
"id": "e7ec2e57-4540-43fa-b2c7-6be5a0ef7f42",
"name": "Community Mental Health Support",
"alternate_name": "MyCity Mental Health Group",
"description": "Comprehensive Mental Health Services available to residents of MyCity including CBT and Counselling. This is not an emergency service and should not be used as an alternative to hospital and GP services."
},
"required_documents": [
{
"id": "f6ad7e69-b9c8-42ce-92db-92cedb4c05c0",
"document": "Any official identification document (Passport, Driver's Licence, identity card) and evidence of address such as an official letter from local or national government. A driver's license which shows your name, photograph, and address can be used as a sole identification document.",
"uri": "http://example.com"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"attributes": [
{
"id": "ae58cc39-8b70-4ab1-8aea-786882e5ac8e",
"link_type": "link_type",
"link_entity": "link_entity",
"value": "value",
"taxonomy_term": {
"id": "3f7b145d-84af-42d7-8fae-eaca714b02b2",
"code": "code",
"name": "name",
"description": "description",
"parent_id": "0bc248fa-dc27-4650-9ba4-8f1a24ef16a2",
"taxonomy": "taxonomy",
"taxonomy_detail": {
"id": "5c4d79d7-cc55-470e-9f1f-8cad074e4892",
"name": "name",
"description": "description",
"uri": "http://example.com",
"version": "version"
},
"language": "eng",
"term_uri": "http://example.com"
}
}
],
"metadata": [
{
"id": "6cd71e9f-1013-49d9-8370-26b8f59d3e5a",
"resource_type": "location",
"last_action_date": "2011-01-01",
"last_action_type": "update",
"field_name": "name",
"previous_value": "MyCity Civic Center",
"replacement_value": "MyCity New Civic Center",
"updated_by": "Ann Persona"
}
]
}
The following compliance rules apply to this endpoint
Required by HSDS? Yes
Required by Open Referral UK? Yes
Response details
This API response will return service data.
The /services endpoint
- GET /services
Retrieves paginated listings of services that only have one-to-one fields in them.
Retrieve fully nested service with all related data with id.
- Query Parameters
search (string) – Full text search.
page (integer) – Page number of paginated result.
per_page (integer) – Number of results requested in a single page.
format (string) – Return results in the specified format. Default is json. Could be ndjson which should stream all the results without pagination.
taxonomy_term_id (string) – Search for services with particular taxonomy_term.
taxonomy_id (string) – Search for services which contain any term with this taxonomy.
organization_id (string) – Search for services which contain services that that this organization provides.
modified_after (string) – Return all results modified on or after this datetime.
minimal (boolean) – Return array of just service ‘id’ and ‘modified_date’. When using this parameter aim to return all services within one call.
full (boolean) – Return a fully nested service, service_at_location, or organization based on the request.
- Status Codes
200 OK – A paginated list of services that only have one-to-one fields in them.
{
"total_items": 10,
"total_pages": 10,
"page_number": 1,
"size": 1,
"first_page": true,
"last_page": false,
"empty": false,
"contents": [
{
"id": "ac148810-d857-441c-9679-408f346de14b",
"name": "Community Counselling",
"alternate_name": "MyCity Counselling Services",
"description": "Counselling Services provided by trained professionals. Suitable for people with mental health conditions such as anxiety, depression, or eating disorders as well as people experiencing difficult life events and circumstances. ",
"url": "http://example.com/counselling",
"email": "[email protected]",
"status": "active",
"interpretation_services": "Interpretation services are available in Urdu, Polish, and Slovak",
"application_process": "If you are an NHS patient please ask your GP for a referral letter, we will then be in touch with you directly. If you are not an NHS patient you should ring our reception to arrange an appointment",
"fees_description": "Non-NHS patients are expected to pay for their counselling sessions. We charge a flat rate per hour of counselling. The current rate is \u00a350 per hour. Please see our website for up to date prices.",
"wait_time": "wait_time",
"fees": "fees_description",
"accreditations": "All of our practitioners are accredited by the BASC, UKCP, and the Professional Standards Body",
"eligibility_description": "This service is intended for all people aged 12 and over who require counselling services in the MyCity area",
"minimum_age": 12,
"maximum_age": 100,
"assured_date": "2005-01-01",
"assurer_email": "[email protected]",
"licenses": "licences",
"alert": "Following COVID-19 we have moved most of our counselling sessions online. Please contact the reception if you require further information.",
"last_modified": "2023-03-15T10:30:45.123Z",
"organization": {
"id": "d9d5e0f5-d3ce-4f73-9a2f-4dd0ecc6c610",
"name": "Example Organization Inc.",
"alternate_name": "Example Org",
"description": "Example Org is a non-profit organization dedicated to providing services to qualified beneficiaries",
"email": "[email protected]",
"website": "http://example.com",
"tax_status": "tax_status",
"year_incorporated": 2011,
"legal_status": "Limited Company",
"logo": "https://openreferral.org/wp-content/uploads/2018/02/OpenReferral_Logo_Green-4-1.png",
"uri": "http://example.com",
"parent_organization_id": "cd09a387-91f4-4555-94ec-e799c35344cd"
},
"program": {
"id": "e7ec2e57-4540-43fa-b2c7-6be5a0ef7f42",
"name": "Community Mental Health Support",
"alternate_name": "MyCity Mental Health Group",
"description": "Comprehensive Mental Health Services available to residents of MyCity including CBT and Counselling. This is not an emergency service and should not be used as an alternative to hospital and GP services."
}
}
]
}
The following compliance rules apply to this endpoint
Required by HSDS? Yes
Required by Open Referral UK? Yes
Required parameters for Open Referral UK page
Response details
This API response will return service data.
The /taxonomies/{id} endpoint
{
"id": "5c4d79d7-cc55-470e-9f1f-8cad074e4892",
"name": "name",
"description": "description",
"uri": "http://example.com",
"version": "version"
}
The following compliance rules apply to this endpoint
Required by HSDS? No
Required by Open Referral UK? Yes
Response details
This API response will return taxonomy data.
The /taxonomies endpoint
- GET /taxonomies
Paginated listing of taxonomies.
Paginated listing of taxonomies.
- Query Parameters
search (string) – Full text search.
page (integer) – Page number of paginated result.
per_page (integer) – Number of results requested in a single page.
format (string) – Return results in the specified format. Default is json. Could be ndjson which should stream all the results without pagination.
- Status Codes
200 OK – Paginated listing of taxonomies.
{
"total_items": 10,
"total_pages": 10,
"page_number": 1,
"size": 1,
"first_page": true,
"last_page": false,
"empty": false,
"contents": [
{
"id": "5c4d79d7-cc55-470e-9f1f-8cad074e4892",
"name": "name",
"description": "description",
"uri": "http://example.com",
"version": "version"
}
]
}
The following compliance rules apply to this endpoint
Required by HSDS? No
Required by Open Referral UK? Yes
Required parameters for Open Referral UK page
Response details
This API response will return taxonomy data.
The /taxonomy_terms/{id} endpoint
{
"id": "3f7b145d-84af-42d7-8fae-eaca714b02b2",
"code": "code",
"name": "name",
"description": "description",
"parent_id": "0bc248fa-dc27-4650-9ba4-8f1a24ef16a2",
"taxonomy": "taxonomy",
"taxonomy_detail": {
"id": "5c4d79d7-cc55-470e-9f1f-8cad074e4892",
"name": "name",
"description": "description",
"uri": "http://example.com",
"version": "version"
},
"language": "eng",
"term_uri": "http://example.com"
}
The following compliance rules apply to this endpoint
Required by HSDS? No
Required by Open Referral UK? No
Response details
This API response will return taxonomy terms data.
The /taxonomy_terms endpoint
- GET /taxonomy_terms
Paginated listing of taxonomy terms
Full information on a taxonomy term
- Query Parameters
search (string) – Full text search.
page (integer) – Page number of paginated result.
per_page (integer) – Number of results requested in a single page.
format (string) – Return results in the specified format. Default is json. Could be ndjson which should stream all the results without pagination.
taxonomy_id (string) – Search for services which contain any term with this taxonomy.
top_only (boolean) – Only retrieve taxonomy terms that have not child terms.
parent_id (string) – Recieve taxonomy terms that have a parent with this id.
- Status Codes
200 OK – Paginated listing of taxonomy terms
{
"total_items": 10,
"total_pages": 10,
"page_number": 1,
"size": 1,
"first_page": true,
"last_page": false,
"empty": false,
"contents": [
{
"id": "3f7b145d-84af-42d7-8fae-eaca714b02b2",
"code": "code",
"name": "name",
"description": "description",
"parent_id": "0bc248fa-dc27-4650-9ba4-8f1a24ef16a2",
"taxonomy": "taxonomy",
"taxonomy_detail": {
"id": "5c4d79d7-cc55-470e-9f1f-8cad074e4892",
"name": "name",
"description": "description",
"uri": "http://example.com",
"version": "version"
},
"language": "eng",
"term_uri": "http://example.com"
}
]
}
The following compliance rules apply to this endpoint
Required by HSDS? No
Required by Open Referral UK? No
Required parameters for Open Referral UK page
Response details
This API response will return taxonomy terms data.
The /organizations/{id} endpoint
- GET /organizations/{id}
Fully nested organization with service array that contains simple information which could only contain the service.id.
Fully nested organization with service array that contains simple information which could only contain the service.id.
- Parameters
id (string) – The id of the organization that the request is intended to retrieve.
- Query Parameters
full_service (boolean) – Fully nested organization with service array that contains full service information.
- Status Codes
200 OK – Fully nested organization with service array that contains simple information which could only contain the service.id.
{
"id": "d9d5e0f5-d3ce-4f73-9a2f-4dd0ecc6c610",
"name": "Example Organization Inc.",
"alternate_name": "Example Org",
"description": "Example Org is a non-profit organization dedicated to providing services to qualified beneficiaries",
"email": "[email protected]",
"website": "http://example.com",
"tax_status": "tax_status",
"year_incorporated": 2011,
"legal_status": "Limited Company",
"logo": "https://openreferral.org/wp-content/uploads/2018/02/OpenReferral_Logo_Green-4-1.png",
"uri": "http://example.com",
"parent_organization_id": "cd09a387-91f4-4555-94ec-e799c35344cd",
"funding": [
{
"id": "1f2df32c-bf08-4b8e-bd6f-e834014b19bc",
"source": "This service is funded partially by the MyCity local government and via grants made by charity funding bodies. We also operate a for-profit department which is used to partially cover the expense of the public service"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"locations": [
{
"id": "3a19ff88-4620-4d17-9830-ac1d859eb5d5",
"location_type": "physical",
"url": "http://example.com",
"name": "MyCity Civic Center",
"alternate_name": "Civic Center",
"description": "MyCity Civic Center is located on Main Street and contains facilities for a number of civic and community services available.",
"transportation": "MyCity Civic Center is serviced by the number 1 Bus and is a short walk from the Main Street Metro Station",
"latitude": 100,
"longitude": 101,
"external_identifier": "10092008082",
"external_identifier_type": "UPRN",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
],
"addresses": [
{
"id": "74706e55-df26-4b84-80fe-ecc30b5befb4",
"attention": "A. Persona",
"address_1": "1-30 Main Street",
"address_2": "MyVillage",
"city": "MyCity",
"region": "MyRegion",
"state_province": "MyState",
"postal_code": "ABC 1234",
"country": "US",
"address_type": "postal"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"accessibility": [
{
"id": "afcf296e-1cb2-4139-9c88-33d587d1a50b",
"description": "The building is equipped with induction loops for hearing aids. Wheelchair access is possible on all levels.",
"details": "Switch hearing aid to T-coil to access the induction loop facility.",
"url": "http://example.com"
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
]
}
],
"programs": [
{
"id": "e7ec2e57-4540-43fa-b2c7-6be5a0ef7f42",
"name": "Community Mental Health Support",
"alternate_name": "MyCity Mental Health Group",
"description": "Comprehensive Mental Health Services available to residents of MyCity including CBT and Counselling. This is not an emergency service and should not be used as an alternative to hospital and GP services."
}
],
"organization_identifiers": [
{
"id": "d4dbcebc-0802-47cb-8651-b937ac4f2f3e",
"identifier_scheme": "GB-COH",
"identifier_type": "Company number",
"identifier": "1234567"
}
],
"services": [
{
"id": "ac148810-d857-441c-9679-408f346de14b",
"name": "Community Counselling",
"alternate_name": "MyCity Counselling Services",
"description": "Counselling Services provided by trained professionals. Suitable for people with mental health conditions such as anxiety, depression, or eating disorders as well as people experiencing difficult life events and circumstances. ",
"url": "http://example.com/counselling",
"email": "[email protected]",
"status": "active",
"interpretation_services": "Interpretation services are available in Urdu, Polish, and Slovak",
"application_process": "If you are an NHS patient please ask your GP for a referral letter, we will then be in touch with you directly. If you are not an NHS patient you should ring our reception to arrange an appointment",
"fees_description": "Non-NHS patients are expected to pay for their counselling sessions. We charge a flat rate per hour of counselling. The current rate is \u00a350 per hour. Please see our website for up to date prices.",
"wait_time": "wait_time",
"fees": "fees_description",
"accreditations": "All of our practitioners are accredited by the BASC, UKCP, and the Professional Standards Body",
"eligibility_description": "This service is intended for all people aged 12 and over who require counselling services in the MyCity area",
"minimum_age": 12,
"maximum_age": 100,
"assured_date": "2005-01-01",
"assurer_email": "[email protected]",
"licenses": "licences",
"alert": "Following COVID-19 we have moved most of our counselling sessions online. Please contact the reception if you require further information.",
"last_modified": "2023-03-15T10:30:45.123Z",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
],
"service_areas": [
{
"id": "381c64f1-a724-4884-9c21-ac96c21cca3e",
"name": "The service is available to all residents of the MyCity area. We provide the service in our offices or via video conferencing to any who can provide evidence of their residency.",
"description": "The service is available to all residents of the MyCity area, including all postcodes starting with AB1, AB2, and AB3",
"extent": "extent",
"extent_type": "geojson",
"uri": "http://example.com"
}
],
"service_at_locations": [
{
"id": "e94c9f38-1e8f-4564-91d4-d53501ab1765",
"description": "Counselling Services provided by trained professionals in the MyCity area.",
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
],
"location": {
"id": "3a19ff88-4620-4d17-9830-ac1d859eb5d5",
"location_type": "physical",
"url": "http://example.com",
"name": "MyCity Civic Center",
"alternate_name": "Civic Center",
"description": "MyCity Civic Center is located on Main Street and contains facilities for a number of civic and community services available.",
"transportation": "MyCity Civic Center is serviced by the number 1 Bus and is a short walk from the Main Street Metro Station",
"latitude": 100,
"longitude": 101,
"external_identifier": "10092008082",
"external_identifier_type": "UPRN",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
],
"addresses": [
{
"id": "74706e55-df26-4b84-80fe-ecc30b5befb4",
"attention": "A. Persona",
"address_1": "1-30 Main Street",
"address_2": "MyVillage",
"city": "MyCity",
"region": "MyRegion",
"state_province": "MyState",
"postal_code": "ABC 1234",
"country": "US",
"address_type": "postal"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"accessibility": [
{
"id": "afcf296e-1cb2-4139-9c88-33d587d1a50b",
"description": "The building is equipped with induction loops for hearing aids. Wheelchair access is possible on all levels.",
"details": "Switch hearing aid to T-coil to access the induction loop facility.",
"url": "http://example.com"
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
]
}
}
],
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
],
"funding": [
{
"id": "1f2df32c-bf08-4b8e-bd6f-e834014b19bc",
"source": "This service is funded partially by the MyCity local government and via grants made by charity funding bodies. We also operate a for-profit department which is used to partially cover the expense of the public service"
}
],
"cost_options": [
{
"id": "1fdf4d39-3d80-484d-9f92-a8ffa08621e7",
"valid_from": "2020-01-01",
"valid_to": "2022-12-31",
"option": "Under 18s and Over 60s",
"currency": "gbp",
"amount": 35,
"amount_description": "per 1 hour session"
}
],
"program": {
"id": "e7ec2e57-4540-43fa-b2c7-6be5a0ef7f42",
"name": "Community Mental Health Support",
"alternate_name": "MyCity Mental Health Group",
"description": "Comprehensive Mental Health Services available to residents of MyCity including CBT and Counselling. This is not an emergency service and should not be used as an alternative to hospital and GP services."
},
"required_documents": [
{
"id": "f6ad7e69-b9c8-42ce-92db-92cedb4c05c0",
"document": "Any official identification document (Passport, Driver's Licence, identity card) and evidence of address such as an official letter from local or national government. A driver's license which shows your name, photograph, and address can be used as a sole identification document.",
"uri": "http://example.com"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"attributes": [
{
"id": "ae58cc39-8b70-4ab1-8aea-786882e5ac8e",
"link_type": "link_type",
"link_entity": "link_entity",
"value": "value",
"taxonomy_term": {
"id": "3f7b145d-84af-42d7-8fae-eaca714b02b2",
"code": "code",
"name": "name",
"description": "description",
"parent_id": "0bc248fa-dc27-4650-9ba4-8f1a24ef16a2",
"taxonomy": "taxonomy",
"taxonomy_detail": {
"id": "5c4d79d7-cc55-470e-9f1f-8cad074e4892",
"name": "name",
"description": "description",
"uri": "http://example.com",
"version": "version"
},
"language": "eng",
"term_uri": "http://example.com"
}
}
],
"metadata": [
{
"id": "6cd71e9f-1013-49d9-8370-26b8f59d3e5a",
"resource_type": "location",
"last_action_date": "2011-01-01",
"last_action_type": "update",
"field_name": "name",
"previous_value": "MyCity Civic Center",
"replacement_value": "MyCity New Civic Center",
"updated_by": "Ann Persona"
}
]
}
]
}
The following compliance rules apply to this endpoint
Required by HSDS? No
Required by Open Referral UK? No
Response details
This API response will return organization data.
The /organizations endpoint
- GET /organizations
Paginated list of basic Organization information
Paginated list of basic Organization information.
- Query Parameters
search (string) – Full text search.
full_service (boolean) – Fully nested organization with service array that contains full service information.
full (boolean) – Return a fully nested service, service_at_location, or organization based on the request.
page (integer) – Page number of paginated result.
per_page (integer) – Number of results requested in a single page.
format (string) – Return results in the specified format. Default is json. Could be ndjson which should stream all the results without pagination.
- Status Codes
200 OK – Paginated list of basic Organization information.
{
"total_items": 10,
"total_pages": 10,
"page_number": 1,
"size": 1,
"first_page": true,
"last_page": false,
"empty": false,
"contents": [
{
"id": "d9d5e0f5-d3ce-4f73-9a2f-4dd0ecc6c610",
"name": "Example Organization Inc.",
"alternate_name": "Example Org",
"description": "Example Org is a non-profit organization dedicated to providing services to qualified beneficiaries",
"email": "[email protected]",
"website": "http://example.com",
"tax_status": "tax_status",
"year_incorporated": 2011,
"legal_status": "Limited Company",
"logo": "https://openreferral.org/wp-content/uploads/2018/02/OpenReferral_Logo_Green-4-1.png",
"uri": "http://example.com",
"parent_organization_id": "cd09a387-91f4-4555-94ec-e799c35344cd"
}
]
}
The following compliance rules apply to this endpoint
Required by HSDS? No
Required by Open Referral UK? No
Required parameters for Open Referral UK page
Response details
This API response will return organization data.
The /service_at_locations/{id} endpoint
- GET /service_at_locations/{id}
Retrieve fully nested service_at_location with all related data with specified id.
Retrieve fully nested service_at_location with all related data with specified id.
- Parameters
id (string) – The id of the service that the request is intended to retrieve.
- Status Codes
200 OK – Retrieve fully nested service_at_location with all related data with specified id.
{
"id": "e94c9f38-1e8f-4564-91d4-d53501ab1765",
"description": "Counselling Services provided by trained professionals in the MyCity area.",
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
],
"location": {
"id": "3a19ff88-4620-4d17-9830-ac1d859eb5d5",
"location_type": "physical",
"url": "http://example.com",
"name": "MyCity Civic Center",
"alternate_name": "Civic Center",
"description": "MyCity Civic Center is located on Main Street and contains facilities for a number of civic and community services available.",
"transportation": "MyCity Civic Center is serviced by the number 1 Bus and is a short walk from the Main Street Metro Station",
"latitude": 100,
"longitude": 101,
"external_identifier": "10092008082",
"external_identifier_type": "UPRN",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
],
"addresses": [
{
"id": "74706e55-df26-4b84-80fe-ecc30b5befb4",
"attention": "A. Persona",
"address_1": "1-30 Main Street",
"address_2": "MyVillage",
"city": "MyCity",
"region": "MyRegion",
"state_province": "MyState",
"postal_code": "ABC 1234",
"country": "US",
"address_type": "postal"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"accessibility": [
{
"id": "afcf296e-1cb2-4139-9c88-33d587d1a50b",
"description": "The building is equipped with induction loops for hearing aids. Wheelchair access is possible on all levels.",
"details": "Switch hearing aid to T-coil to access the induction loop facility.",
"url": "http://example.com"
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
]
},
"service": {
"id": "ac148810-d857-441c-9679-408f346de14b",
"name": "Community Counselling",
"alternate_name": "MyCity Counselling Services",
"description": "Counselling Services provided by trained professionals. Suitable for people with mental health conditions such as anxiety, depression, or eating disorders as well as people experiencing difficult life events and circumstances. ",
"url": "http://example.com/counselling",
"email": "[email protected]",
"status": "active",
"interpretation_services": "Interpretation services are available in Urdu, Polish, and Slovak",
"application_process": "If you are an NHS patient please ask your GP for a referral letter, we will then be in touch with you directly. If you are not an NHS patient you should ring our reception to arrange an appointment",
"fees_description": "Non-NHS patients are expected to pay for their counselling sessions. We charge a flat rate per hour of counselling. The current rate is \u00a350 per hour. Please see our website for up to date prices.",
"wait_time": "wait_time",
"fees": "fees_description",
"accreditations": "All of our practitioners are accredited by the BASC, UKCP, and the Professional Standards Body",
"eligibility_description": "This service is intended for all people aged 12 and over who require counselling services in the MyCity area",
"minimum_age": 12,
"maximum_age": 100,
"assured_date": "2005-01-01",
"assurer_email": "[email protected]",
"licenses": "licences",
"alert": "Following COVID-19 we have moved most of our counselling sessions online. Please contact the reception if you require further information.",
"last_modified": "2023-03-15T10:30:45.123Z",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
],
"service_areas": [
{
"id": "381c64f1-a724-4884-9c21-ac96c21cca3e",
"name": "The service is available to all residents of the MyCity area. We provide the service in our offices or via video conferencing to any who can provide evidence of their residency.",
"description": "The service is available to all residents of the MyCity area, including all postcodes starting with AB1, AB2, and AB3",
"extent": "extent",
"extent_type": "geojson",
"uri": "http://example.com"
}
],
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
],
"organization": {
"id": "d9d5e0f5-d3ce-4f73-9a2f-4dd0ecc6c610",
"name": "Example Organization Inc.",
"alternate_name": "Example Org",
"description": "Example Org is a non-profit organization dedicated to providing services to qualified beneficiaries",
"email": "[email protected]",
"website": "http://example.com",
"tax_status": "tax_status",
"year_incorporated": 2011,
"legal_status": "Limited Company",
"logo": "https://openreferral.org/wp-content/uploads/2018/02/OpenReferral_Logo_Green-4-1.png",
"uri": "http://example.com",
"parent_organization_id": "cd09a387-91f4-4555-94ec-e799c35344cd",
"funding": [
{
"id": "1f2df32c-bf08-4b8e-bd6f-e834014b19bc",
"source": "This service is funded partially by the MyCity local government and via grants made by charity funding bodies. We also operate a for-profit department which is used to partially cover the expense of the public service"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"locations": [
{
"id": "3a19ff88-4620-4d17-9830-ac1d859eb5d5",
"location_type": "physical",
"url": "http://example.com",
"name": "MyCity Civic Center",
"alternate_name": "Civic Center",
"description": "MyCity Civic Center is located on Main Street and contains facilities for a number of civic and community services available.",
"transportation": "MyCity Civic Center is serviced by the number 1 Bus and is a short walk from the Main Street Metro Station",
"latitude": 100,
"longitude": 101,
"external_identifier": "10092008082",
"external_identifier_type": "UPRN",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
],
"addresses": [
{
"id": "74706e55-df26-4b84-80fe-ecc30b5befb4",
"attention": "A. Persona",
"address_1": "1-30 Main Street",
"address_2": "MyVillage",
"city": "MyCity",
"region": "MyRegion",
"state_province": "MyState",
"postal_code": "ABC 1234",
"country": "US",
"address_type": "postal"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"accessibility": [
{
"id": "afcf296e-1cb2-4139-9c88-33d587d1a50b",
"description": "The building is equipped with induction loops for hearing aids. Wheelchair access is possible on all levels.",
"details": "Switch hearing aid to T-coil to access the induction loop facility.",
"url": "http://example.com"
}
],
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
],
"schedules": [
{
"id": "48102e86-bb50-41c4-8f1e-e269368c41d1",
"valid_from": "2005-01-01",
"valid_to": "2005-01-01",
"dtstart": "2005-01-01",
"timezone": 3,
"until": "2005-01-01",
"count": 3,
"wkst": "TU",
"freq": "WEEKLY",
"interval": 1,
"byday": "TH,FR",
"byweekno": "41,42",
"bymonthday": "2,3,4",
"byyearday": "2,3,4",
"description": "The service is available from 10 am to 6pm weekdays. The service is not available on public holidays.",
"opens_at": "10:00:00",
"closes_at": "18:00:00",
"schedule_link": "http://example.com",
"attending_type": "You can attend this service in-person or remotely via video conferencing",
"notes": "Some of our staff will be unavailable during their lunch break which may be any 30 minute period between 1200 and 1400"
}
]
}
],
"programs": [
{
"id": "e7ec2e57-4540-43fa-b2c7-6be5a0ef7f42",
"name": "Community Mental Health Support",
"alternate_name": "MyCity Mental Health Group",
"description": "Comprehensive Mental Health Services available to residents of MyCity including CBT and Counselling. This is not an emergency service and should not be used as an alternative to hospital and GP services."
}
],
"organization_identifiers": [
{
"id": "d4dbcebc-0802-47cb-8651-b937ac4f2f3e",
"identifier_scheme": "GB-COH",
"identifier_type": "Company number",
"identifier": "1234567"
}
]
},
"funding": [
{
"id": "1f2df32c-bf08-4b8e-bd6f-e834014b19bc",
"source": "This service is funded partially by the MyCity local government and via grants made by charity funding bodies. We also operate a for-profit department which is used to partially cover the expense of the public service"
}
],
"cost_options": [
{
"id": "1fdf4d39-3d80-484d-9f92-a8ffa08621e7",
"valid_from": "2020-01-01",
"valid_to": "2022-12-31",
"option": "Under 18s and Over 60s",
"currency": "gbp",
"amount": 35,
"amount_description": "per 1 hour session"
}
],
"program": {
"id": "e7ec2e57-4540-43fa-b2c7-6be5a0ef7f42",
"name": "Community Mental Health Support",
"alternate_name": "MyCity Mental Health Group",
"description": "Comprehensive Mental Health Services available to residents of MyCity including CBT and Counselling. This is not an emergency service and should not be used as an alternative to hospital and GP services."
},
"required_documents": [
{
"id": "f6ad7e69-b9c8-42ce-92db-92cedb4c05c0",
"document": "Any official identification document (Passport, Driver's Licence, identity card) and evidence of address such as an official letter from local or national government. A driver's license which shows your name, photograph, and address can be used as a sole identification document.",
"uri": "http://example.com"
}
],
"contacts": [
{
"id": "1e7efce3-639b-4880-940c-b95cd30cdb50",
"name": "Ann Persona",
"title": "Reception Manager",
"department": "Reception",
"email": "[email protected]",
"phones": [
{
"id": "1554f2e2-a373-45db-a3fa-9fc48a61c15e",
"number": "\"+44 1234 234567\"",
"extension": 100,
"type": "voice",
"description": "Our main reception phone number. The phones will be available from 0800 (8am) until 1800 (6pm) local time. There may be some slight delays in answering your call if we are busy.",
"languages": [
{
"id": "2989d3ed-c547-48f8-8f9d-432d81c7892e",
"name": "Urdu",
"code": "ur",
"note": "Translation services provided via bilingual staff when they are available"
}
]
}
]
}
],
"attributes": [
{
"id": "ae58cc39-8b70-4ab1-8aea-786882e5ac8e",
"link_type": "link_type",
"link_entity": "link_entity",
"value": "value",
"taxonomy_term": {
"id": "3f7b145d-84af-42d7-8fae-eaca714b02b2",
"code": "code",
"name": "name",
"description": "description",
"parent_id": "0bc248fa-dc27-4650-9ba4-8f1a24ef16a2",
"taxonomy": "taxonomy",
"taxonomy_detail": {
"id": "5c4d79d7-cc55-470e-9f1f-8cad074e4892",
"name": "name",
"description": "description",
"uri": "http://example.com",
"version": "version"
},
"language": "eng",
"term_uri": "http://example.com"
}
}
],
"metadata": [
{
"id": "6cd71e9f-1013-49d9-8370-26b8f59d3e5a",
"resource_type": "location",
"last_action_date": "2011-01-01",
"last_action_type": "update",
"field_name": "name",
"previous_value": "MyCity Civic Center",
"replacement_value": "MyCity New Civic Center",
"updated_by": "Ann Persona"
}
]
}
}
The following compliance rules apply to this endpoint
Required by HSDS? No
Required by Open Referral UK? Yes
Response details
This API response will return service at location data.
The /service_at_locations endpoint
- GET /service_at_locations
Retrieve paginated listings of service_at_location that only have one-to-one fields in them.
Retrieve paginated listings of service_at_location that only have one-to-one fields in them.
- Query Parameters
search (string) – Full text search.
taxonomy_term_id (string) – Search for services with particular taxonomy_term.
taxonomy_id (string) – Search for services which contain any term with this taxonomy.
organization_id (string) – Search for services which contain services that that this organization provides.
modified_after (string) – Return all results modified on or after this datetime.
full (boolean) – Return a fully nested service, service_at_location, or organization based on the request.
page (integer) – Page number of paginated result.
per_page (integer) – Number of results requested in a single page.
format (string) – Return results in the specified format. Default is json. Could be ndjson which should stream all the results without pagination.
postcode (string) – The postcode or zip code of a point used to check service coverage. If service_area is available, only return results where the postcode exists within the service_area. If proximity is provided, only show results within the proximity from the centroid of the postcode.
proximity (string) – Return services that exist within meters from the centroid of the provided postcode
- Status Codes
200 OK – Retrieve paginated listings of service_at_location that only have one-to-one fields in them.
{
"total_items": 10,
"total_pages": 10,
"page_number": 1,
"size": 1,
"first_page": true,
"last_page": false,
"empty": false,
"contents": [
{
"id": "e94c9f38-1e8f-4564-91d4-d53501ab1765",
"description": "Counselling Services provided by trained professionals in the MyCity area.",
"location": {
"id": "3a19ff88-4620-4d17-9830-ac1d859eb5d5",
"location_type": "physical",
"url": "http://example.com",
"name": "MyCity Civic Center",
"alternate_name": "Civic Center",
"description": "MyCity Civic Center is located on Main Street and contains facilities for a number of civic and community services available.",
"transportation": "MyCity Civic Center is serviced by the number 1 Bus and is a short walk from the Main Street Metro Station",
"latitude": 100,
"longitude": 101,
"external_identifier": "10092008082",
"external_identifier_type": "UPRN"
},
"service": {
"id": "ac148810-d857-441c-9679-408f346de14b",
"name": "Community Counselling",
"alternate_name": "MyCity Counselling Services",
"description": "Counselling Services provided by trained professionals. Suitable for people with mental health conditions such as anxiety, depression, or eating disorders as well as people experiencing difficult life events and circumstances. ",
"url": "http://example.com/counselling",
"email": "[email protected]",
"status": "active",
"interpretation_services": "Interpretation services are available in Urdu, Polish, and Slovak",
"application_process": "If you are an NHS patient please ask your GP for a referral letter, we will then be in touch with you directly. If you are not an NHS patient you should ring our reception to arrange an appointment",
"fees_description": "Non-NHS patients are expected to pay for their counselling sessions. We charge a flat rate per hour of counselling. The current rate is \u00a350 per hour. Please see our website for up to date prices.",
"wait_time": "wait_time",
"fees": "fees_description",
"accreditations": "All of our practitioners are accredited by the BASC, UKCP, and the Professional Standards Body",
"eligibility_description": "This service is intended for all people aged 12 and over who require counselling services in the MyCity area",
"minimum_age": 12,
"maximum_age": 100,
"assured_date": "2005-01-01",
"assurer_email": "[email protected]",
"licenses": "licences",
"alert": "Following COVID-19 we have moved most of our counselling sessions online. Please contact the reception if you require further information.",
"last_modified": "2023-03-15T10:30:45.123Z",
"organization": {
"id": "d9d5e0f5-d3ce-4f73-9a2f-4dd0ecc6c610",
"name": "Example Organization Inc.",
"alternate_name": "Example Org",
"description": "Example Org is a non-profit organization dedicated to providing services to qualified beneficiaries",
"email": "[email protected]",
"website": "http://example.com",
"tax_status": "tax_status",
"year_incorporated": 2011,
"legal_status": "Limited Company",
"logo": "https://openreferral.org/wp-content/uploads/2018/02/OpenReferral_Logo_Green-4-1.png",
"uri": "http://example.com",
"parent_organization_id": "cd09a387-91f4-4555-94ec-e799c35344cd"
},
"program": {
"id": "e7ec2e57-4540-43fa-b2c7-6be5a0ef7f42",
"name": "Community Mental Health Support",
"alternate_name": "MyCity Mental Health Group",
"description": "Comprehensive Mental Health Services available to residents of MyCity including CBT and Counselling. This is not an emergency service and should not be used as an alternative to hospital and GP services."
}
}
}
]
}
The following compliance rules apply to this endpoint
Required by HSDS? No
Required by Open Referral UK? Yes
Required parameters for Open Referral UK page
Response details
This API response will return service at location data.