API Reference

In addition to the HSDS Schemas, HSDS provides an API Reference to support standardising how systems provide read or read/write access to information on organizations, services, locations, and the details about them. This specification provides most of the functionality needed for simple access and exchange of data, and systems are encouraged to use it as a blueprint for implementing their own API platforms.

Unlike with the HSDS Schemas where we can provide canonical JSON Schema representations of the model, we are unaware of a comparable technology for specifying API compliance with this specification. We do provide a canonical reference formatted as OpenAPI specification which can be taken and used as a starting point. However, OpenAPI is designed for describing individual APIs rather than specifying the requirements for arbitrary API conformant to the specification. It also does not support describing the intended behavior for systems handing requests with multiple filter parameters.

To overcome this limitation, the API specification on this page uses the key words “MUST”, “REQUIRED” and “OPTIONAL” in accordance with RFC 2119 to describe whether each endpoint is required by the API Specification. This is used alongside the details of the canonical OpenAPI formatted reference file to measure compliance with the API Specification.

The current canonical HSDS API specification in OpenAPI 3.1 format is available at the following URL: https://raw.githubusercontent.com/openreferral/specification/3.2/schema/openapi.json

For those more familiar with tools such as SwaggerUI, we provide a Swagger UI representation. Readers should note that due to incompatibilities between Swagger UI and OpenAPI 3.1, the file powering the Swagger UI representation is compiled from the canonical HSDS API specification file. Therefore if there are any conflicts between the Swagger UI representation and the specification defined on this API Reference page, then this specification takes precedence.

If there are errors or omissions in this API specification, you are encouraged to raise issues on on the issue tracker.

OpenAPI Tags

The OpenAPI specification makes use of OpenAPI’s Tag object to tad endpoints with tags drawn from the API Endpoint Requirement codelist. For convenience, these codes and definitions have been reproduced in the OpenAPI file as Tags. If there are any discrepencies between the definitions of these terms between the canonical codelists and the corresponding Tag objects in the OpenAPI file; the canonical codelists take precedence.

Lists and Pagination

API endpoints that return lists of entities, such as services returned by a /services endpoint MUST be paginated. To support this, the HSDS API reference defines the Page schema:

Title	Description	Type	Format	Required
total_items		integer
None	The total number of entities (e.g. services, organizations) returned
total_pages		integer
None	Count of total pages.
page_number		integer
None	The number of the current page
size		integer
None	The number of entities in the current page.
first_page		boolean
None	A Boolean value indicating if this is the first page
last_page		boolean
None	A Boolean value indicating if this is the last page
empty		boolean		Required
None	A Boolean value indicating if there is an empty result set

This acts as a header to all responses containing a list. Ideally, Responses will include all the properties from Page, as well as a contents property. contents is an array containing a list of the appropriate objects (e.g. Services).

Each item in contents will normally contain all its direct properties, but do not need to contain arrays of child entities (e.g. Service Contacts). This is to prevent response data becoming unreasonably large.

Please see the included example responses to see this in practice.

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 non-required metadata field containing a metadata object. Since some API responses can contain a list of many objects — each with their own nested objects — this could result in a large quantity of metadata in the response.

Therefore we wish to be explicit that including the metadata property in each object is OPTIONAL, and API implementors are responsible for considering 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.

The / endpoint

This endpoint is REQUIRED for conforming APIs.

Details

GET /

Retrieve information about this API and its relationship with HSDS.

Retrieve information about this API and its relationship with HSDS.

Status Codes

• 200 OK – A JSON response providing information about this API.

Example Response

{
    "version": "3.0",
    "profile": "https://path/to/profile",
    "openapi_url": "https://raw.githubusercontent.com/openreferral/specification/3.0/schema/openapi.json"
}

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 MUST be a URL which resolves to a location where the information on the HSDS profile of this API is be found.

• openapi_url (URI) – URL of the openapi JSON file which defines this API.

The /services/{id} endpoint

This endpoint is REQUIRED for conforming APIs.

Details

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.

Example Response

{
    "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",
    "additional_urls": [
        {
            "id": "30951f94-7b24-11ef-ba1b-a79405d4dcaa",
            "label": "Website",
            "url": "https://example.org"
        }
    ],
    "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.",
            "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"
                }
            ],
            "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",
        "additional_websites": [
            {
                "id": "30951f94-7b24-11ef-ba1b-a79405d4dcaa",
                "label": "Website",
                "url": "https://example.org"
            }
        ],
        "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"
                        }
                    ]
                }
            ]
        }
    ],
    "capacities": [
        {
            "id": "8896b788-7b3e-11ef-8db9-7f3d040352b3",
            "unit": {
                "id": "8896b788-7b3e-11ef-8db9-7f3d040352b3",
                "name": "Kilogram",
                "scheme": "SI",
                "identifier": "kgm",
                "uri": "https://not-a-real-url.org/standard-international-units/kgm"
            },
            "available": 12,
            "maximum": 10,
            "description": "Beds available for people experiencing homelessness.",
            "updated": "2024-09-25T14:23:06.5+01:00"
        }
    ],
    "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"
            },
            "label": "An Example Label"
        }
    ],
    "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"
        }
    ]
}

Response details

This API response will return service data.

The /services endpoint

This endpoint is REQUIRED for conforming APIs.

Details

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 records with particular taxonomy_term.

• taxonomy_id (string) – Search for records 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.

POST /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 records with particular taxonomy_term.

• taxonomy_id (string) – Search for records 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.

Example Response

{
    "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

Response details

This API response will return service data.

The /taxonomies/{id} endpoint

This endpoint is OPTIONAL for conforming APIs.

Details

GET /taxonomies/{id}

Retrieves full information on a taxonomy by {id}.

Full information on taxonomy.

Parameters

• id (string) – The id of the taxonomy that the request is intended to retrieve.

Status Codes

• 200 OK – Full information on taxonomy.

Example Response

{
    "id": "5c4d79d7-cc55-470e-9f1f-8cad074e4892",
    "name": "name",
    "description": "description",
    "uri": "http://example.com",
    "version": "version"
}

Response details

This API response will return taxonomy data.

The /taxonomies endpoint

This endpoint is OPTIONAL for conforming APIs.

Details

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.

POST /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.

Example Response

{
    "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"
        }
    ]
}

Response details

This API response will return taxonomy data.

The /taxonomy_terms/{id} endpoint

This endpoint is OPTIONAL for conforming APIs.

Details

GET /taxonomy_terms/{id}

Full information on a taxonomy term.

Full information on a taxonomy term.

Parameters

• id (string) – The id of the taxonomy terms that the request is intended to retrieve.

Status Codes

• 200 OK – Full information on a taxonomy term.

Example Response

{
    "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"
}

Response details

This API response will return taxonomy terms data.

The /taxonomy_terms endpoint

This endpoint is OPTIONAL for conforming APIs.

Details

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 records 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

POST /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 records 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

Example Response

{
    "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"
        }
    ]
}

Response details

This API response will return taxonomy terms data.

The /organizations/{id} endpoint

This endpoint is OPTIONAL for conforming APIs.

Details

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.

Example Response

{
    "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",
    "additional_websites": [
        {
            "id": "30951f94-7b24-11ef-ba1b-a79405d4dcaa",
            "label": "Website",
            "url": "https://example.org"
        }
    ],
    "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",
            "additional_urls": [
                {
                    "id": "30951f94-7b24-11ef-ba1b-a79405d4dcaa",
                    "label": "Website",
                    "url": "https://example.org"
                }
            ],
            "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.",
                    "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"
                        }
                    ],
                    "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"
                                }
                            ]
                        }
                    ]
                }
            ],
            "capacities": [
                {
                    "id": "8896b788-7b3e-11ef-8db9-7f3d040352b3",
                    "unit": {
                        "id": "8896b788-7b3e-11ef-8db9-7f3d040352b3",
                        "name": "Kilogram",
                        "scheme": "SI",
                        "identifier": "kgm",
                        "uri": "https://not-a-real-url.org/standard-international-units/kgm"
                    },
                    "available": 12,
                    "maximum": 10,
                    "description": "Beds available for people experiencing homelessness.",
                    "updated": "2024-09-25T14:23:06.5+01:00"
                }
            ],
            "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"
                    },
                    "label": "An Example Label"
                }
            ],
            "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"
                }
            ]
        }
    ]
}

Response details

This API response will return organization data.

The /organizations endpoint

This endpoint is OPTIONAL for conforming APIs.

Details

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.

• taxonomy_term_id (string) – Search for records with particular taxonomy_term.

• taxonomy_id (string) – Search for records which contain any term with this taxonomy.

• 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.

POST /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.

• taxonomy_term_id (string) – Search for records with particular taxonomy_term.

• taxonomy_id (string) – Search for records which contain any term with this taxonomy.

Status Codes

• 200 OK – Paginated list of basic Organization information.

Example Response

{
    "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"
        }
    ]
}

Response details

This API response will return organization data.

The /service_at_locations/{id} endpoint

This endpoint is OPTIONAL for conforming APIs.

Details

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.

Example Response

{
    "id": "e94c9f38-1e8f-4564-91d4-d53501ab1765",
    "description": "Counselling Services provided by trained professionals in the MyCity area.",
    "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"
        }
    ],
    "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",
        "additional_urls": [
            {
                "id": "30951f94-7b24-11ef-ba1b-a79405d4dcaa",
                "label": "Website",
                "url": "https://example.org"
            }
        ],
        "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",
            "additional_websites": [
                {
                    "id": "30951f94-7b24-11ef-ba1b-a79405d4dcaa",
                    "label": "Website",
                    "url": "https://example.org"
                }
            ],
            "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"
                            }
                        ]
                    }
                ]
            }
        ],
        "capacities": [
            {
                "id": "8896b788-7b3e-11ef-8db9-7f3d040352b3",
                "unit": {
                    "id": "8896b788-7b3e-11ef-8db9-7f3d040352b3",
                    "name": "Kilogram",
                    "scheme": "SI",
                    "identifier": "kgm",
                    "uri": "https://not-a-real-url.org/standard-international-units/kgm"
                },
                "available": 12,
                "maximum": 10,
                "description": "Beds available for people experiencing homelessness.",
                "updated": "2024-09-25T14:23:06.5+01:00"
            }
        ],
        "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"
                },
                "label": "An Example Label"
            }
        ],
        "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"
            }
        ]
    }
}

Response details

This API response will return service at location data.

The /service_at_locations endpoint

This endpoint is OPTIONAL for conforming APIs.

Details

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 records with particular taxonomy_term.

• taxonomy_id (string) – Search for records 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.

POST /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 records with particular taxonomy_term.

• taxonomy_id (string) – Search for records 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.

Example Response

{
    "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."
                }
            }
        }
    ]
}

Response details

This API response will return service at location data.