Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

Identification | Organization

A formally or informally recognized grouping of people or organizations formed for the purpose of achieving some form of collective action. Includes companies, institutions, corporations, departments, community groups, healthcare practice groups, etc.

References

1. Read

Returns a single Organization for the specified id.

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:

200 OK
404 Not Found
500 Internal Server Error

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.

Name Parameter Type Description Path
_id token The logical id of the resource (ODS Code) Organization.id
_lastUpdated date To select resources based on the last time they were changed Organization.meta.lastUpdated
identifier token The identifier for the organization (ODS Code) Organization.identifier
name string A portion of the organization’s name Organization.name
active token Whether the organization’s record is still in active use Organization.active
address-postalcode string A postcode specified in an address Organization.address.postalCode
address-city string A city specified in an address Organization.address.city
ods-org-role token A role of the organization Organization.extension(‘https://fhir.nhs.uk/STU3/StructureDefinition/Extension-ODSAPI-OrganizationRole-1’).extension(‘role’).value
ods-org-primaryRole token Whether a role of the organization is it’s primary role Organization.extension(‘https://fhir.nhs.uk/STU3/StructureDefinition/Extension-ODSAPI-OrganizationRole-1’).extension(‘primaryrole’).value

Additional Parameters:

Name Parameter Type Description Allowable Content
_count number Number of results per page Whole number
_summary string Search only: just return a count of the matching resources, without returning the actual matches ‘count’

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:

Prefix Description
gt greater than

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:

Modifier Description
count Search only: just return a count of the matching resources, without returning the actual matches

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.

HTTP Code issue.severity issue.code issue.details.code issue.details.display
404 error not-found NO_RECORD_FOUND No record found
400 error code-invalid INVALID_CODE_SYSTEM Invalid code system
400 error code-invalid INVALID_CODE_VALUE Invalid code value
400 error code-invalid INVALID_IDENTIFIER_SYSTEM Invalid identifier system
400 error code-invalid INVALID_IDENTIFIER_VALUE Invalid identifier value
400 error invalid INVALID_PARAMETER Invalid parameter
400 error invalid INVALID_VALUE An input field has an invalid value for its type
Tags: rest identification

All content is available under the Open Government Licence v3.0, except where otherwise stated