Identification | Organization

0. References

1. Read

Returns a single Organization for the specified id (ODS code).

By default the response will be returned in JSON, however XML is also supported.

1.1. Response

A full set of response codes can be found here API Response Codes. FHIR Servers SHALL support the following response codes:

2. Search

Returns a Bundle of all Organization resources that match the specified search criteria.

By default the response will be returned in JSON, however XML is also supported.

2.1. Search Parameters

The search parameters supported in the API for the Organization resource are in the table below. The parameters can be used independently or in combination to help refine the search results returned. This section outlines the search parameter syntax used, with some examples provided.

Additional Parameters:

2.1.1. _id

See _id for details on this parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?_id=RTG

Return Organization resource where ODS Code logical id matches RTG (Derby Teaching Hospitals NHS Foundation Trust).

2.1.2. _lastUpdated

See _lastUpdated for details on this parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?_lastUpdated=gt2017-04-01

Return all Organization resources where the Organization record was updated after 2017-04-01.

The supported prefixes for this search parameter are:

2.1.3. identifier

See token for details on this parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?identifier=https://fhir.nhs.uk/Id/ods-organization-code|RTG


Return the Organization resource with ODS Code of RTG (Derby Teaching Hospitals NHS Foundation Trust).

GET https://directory.spineservices.nhs.uk/STU3/Organization?identifier=RTG


Return the Organization resource with ODS Code of RTG (Derby Teaching Hospitals NHS Foundation Trust).

2.1.4. name

See string for details on this parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?name=Derby Teaching Hospitals NHS Foundation Trust

Return all Organization resources with name of Derby Teaching Hospitals NHS Foundation Trust.

Search expressions must:

• Contain a minimum of 3 characters and a maximum of 100 characters
• Only include characters (A-Z a-z 0-9 &()’+ -_ -./ : : @) ‘Space’

Begins with:

By default, a field matches a string query if the value of the field equals or starts with the supplied parameter value, after both have been normalized by case and accent.

To search for a name that begins with “Leeds”, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?name=Leeds

This will return the ODS records that have an Organization name that begins with “Leeds” e.g. RQS98 - Leeds Chest Clinic and RX847 - Leeds Central Ambulance Station etc.

Contained match:

The :contains modifier returns results that include the supplied parameter value anywhere within the field being searched.

To search for a name that contains “Leeds”, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?name:contains=Leeds

This will return the ODS records that have an Organization name that contains the word “Leeds” within its name e.g 5HL18 - South Leeds Clinical Assessment Service and B86013 - The North Leeds Medical Practice etc.

Exact match:

The :exact modifier returns results that match the entire supplied parameter, including casing and accents.

To search for an exact name e.g. “LEEDS TEACHING HOSPITALS NHS TRUST”, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?name:exact=LEEDS TEACHING HOSPITALS NHS TRUST

This will return the ODS record where the Organization name is exactly “LEEDS TEACHING HOSPITALS NHS TRUST”.

2.1.5. active

See token for details on this parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?active=true

Return all Organization resources with active value of true.

An ODS record contains a status of active or inactive.

To search for an active ODS record, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?active=true

This will return all the ODS records where the status of the organisation is active.

To search for an for an inactive ODS record, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?active=false

This will return all the ODS records where the status of the organisation is inactive.

2.1.6. address-postalcode

See string for details on this parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?address-postalcode=DE22 3NE

Return all Organization resources with Postcode of DE22 3NE.

Search expressions must:

• Contain a minimum of 2 characters
• All characters MUST be alphanumeric

Begins with:

By default, a field matches a string query if the value of the field equals or starts with the supplied parameter value, after both have been normalized by case and accent.

To search for a postcode that begins with “LS1”, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?address-postalcode=LS1

This will return all the ODS records with a postcode beginning with LS1 (All organisations with postcodes including LS1, LS10, LS11, etc.)

Contained match:

The :contains modifier returns results that include the supplied parameter value anywhere within the field being searched.

To search for a postcode that contains with “LS6 4”, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?address-postalcode:contains=LS6 4

This will return all the ODS records with a postcode containing LS6 4 anywhere in the postcode e.g. Sandfield House NH, LS6 4DZ

Exact match:

The :exact modifier returns results that match the entire supplied parameter, including casing and accents.

This will return all the ODS records with a postcode

To search for an exact postcode “LS6 4JN” the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?address-postalcode:exact=LS6 4JN

This will return all the ODS records with a postcode of LS6 4JN e.g Meanwood Health Centre, LS6 4JN

2.1.7. address-city

See string for details on this parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?address-city=Derby

Return all Organization resources with City of Derby.

Begins with:

By default, a field matches a string query if the value of the field equals or starts with the supplied parameter value, after both have been normalized by case and accent.

To search for a city that begins with “Peter”, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?address-city=Peter

This will return the ODS records that have a city that begins with “Peter” e.g. Peterborough, Petersfield, Peterlee etc.

Contained match:

The :contains modifier returns results that include the supplied parameter value anywhere within the field being searched.

To search for a city that contains “land”, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?address-city:contains=land

This will return the ODS records that have a city that contains the word “land” e.g Hayling Island, Llandrindod Wells, Sunderland etc.

Exact match:

The :exact modifier returns results that match the entire supplied parameter, including casing and accents.

To search for an exact name e.g. “DERBY” , the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?name:exact=DERBY

This will return the ODS record where the city is exactly “DERBY”.

2.1.8. ods-org-role

See token for details on this parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=https://directory.spineservices.nhs.uk/STU3/STU3/CodeSystem/ODSAPI-OrganizationRole-1|197

Return all Organization resources with a role system of https://directory.spineservices.nhs.uk/STU3/STU3/CodeSystem/ODSAPI-OrganizationRole-1 and a code of 197 (NHS Trust).

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=197

Return all Organization resources with a role code of 197 (NHS Trust).

An ODS record contains one or many roles.

Composite Search Parameters:

Composite search parameters support joining single values. Multiple roles can be queried using an ‘AND’ or an ‘OR’ search.

AND Parameters

An ‘AND’ search can be executed by repeating the parameter. To search for ODS records that have the roles ‘76 - GP PRACTICE’ AND ‘177 - PRESCRIBING COST CENTRE’, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=https://directory.spineservices.nhs.uk/STU3/STU3/CodeSystem/ODSAPI-OrganizationRole-1|76&ods-org-role=https://directory.spineservices.nhs.uk/STU3/STU3/CodeSystem/ODSAPI-OrganizationRole-1|177

or

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=76&ods-org-role=177

This will return ODS records that have the roles ‘76 - GP PRACTICE’ AND ‘177 - PRESCRIBING COST CENTRE’ e.g. A81001 - THE DENSHAM SURGERY.

OR Parameters

An ‘OR’ search can be executed by using a single parameter with multiple values separated by a ,. To search for an ODS record with the roles ‘197 - NHS TRUST’ OR ‘198 - NHS TRUST SITE’, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=https://directory.spineservices.nhs.uk/STU3/STU3/CodeSystem/ODSAPI-OrganizationRole-1|197,198

or

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=197,198

This will return the ODS records that have either role ‘197 - NHS TRUST’ OR ‘198 - NHS TRUST SITE’.

AND and OR Parameters

‘AND’ parameters and ‘OR’ parameters may also be combined. To search for an ODS record with the role ‘157 - NON-NHS ORGANISATION’ AND either roles ‘29 - TREATMENT CENTRE’ OR ‘15 - REG’D UNDER PART 2 CARE STDS ACT 2000’.

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=https://directory.spineservices.nhs.uk/STU3/STU3/CodeSystem/ODSAPI-OrganizationRole-1|157&ods-org-role=https://directory.spineservices.nhs.uk/STU3/STU3/CodeSystem/ODSAPI-OrganizationRole-1|29,15

or

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=157&ods-org-role=29,15

This will return the ODS records that have the following role codes:

• ‘157 NON-NHS ORGANISATION’ AND ‘29 TREATMENT CENTRE’

• ‘157 NON-NHS ORGANISATION’ AND ‘15 REG’D UNDER PART 2 CARE STDS ACT 2000’

2.1.9. ods-org-primaryRole

See token for details on this parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-primaryRole=true

Return all Organization resources with code value of true.

This search parameter MUST be used in conjunction with ods-org-role, it cannot be executed independently.

An ODS record contains one role with a status of primary role.

To search for an ODS record with a specified primary role ‘157 - NON-NHS ORGANISATION’, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=https://directory.spineservices.nhs.uk/STU3/STU3/CodeSystem/ODSAPI-OrganizationRole-1|157&ods-org-primaryRole=true

or

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=157&ods-org-primaryRole=true

This will return all the ODS records with a primary role of ‘157 - NON-NHS ORGANISATION’.

To search for an ODS record without a specified primary role of ‘76 - GP PRACTICE’, the following search should be executed:

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=https://directory.spineservices.nhs.uk/STU3/STU3/CodeSystem/ODSAPI-OrganizationRole-1|76&ods-org-primaryRole=false

or

GET https://directory.spineservices.nhs.uk/STU3/Organization?ods-org-role=76&ods-org-primaryRole=true

This will return all the ODS records with a role of ‘76 - GP PRACTICE’ which is not a primary role.

2.1.10. _count

See _count for details on this result parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?_count=10

Return Organization resources with a maximum of 10 resources per page.

Paging

With the scale of the ODS data, the results returned from certain queries could be extensive and require a method for browsing the details returned. FHIR pagination provides the ability to return paged results, making the navigating of the results user friendly. It is possible to control the number of results returned using the _count parameter. The maximum page size is 20. See Paging for further information.

2.1.11. _summary

See _summary for details on this result parameter.

GET https://directory.spineservices.nhs.uk/STU3/Organization?_summary=count

Return a summary of matching Organization resources, without returning the actual matches.

The supported modifiers for this search parameter are:

2.2. Search Response

If the search succeeds, the returned content is a Bundle with type = searchset containing the results of the search as a list of resources.

If the search fails (cannot be executed, not that there are no matches), the return value is a status code 4xx or 5xx with an OperationOutcome that conforms to the Spine-OperationOutcome-1 resource.

A full set of response codes can be found here API Response Codes.

The below table summarises the types of error that could occur, and the HTTP response codes, along with the values to expect in the OperationOutcome in the response body.