FHIR Practitioner

Base Path: /fhir/4.0/Practitioner

Version: 2.0.0

The FHIR Practitioner API allows you to search for and look up practitioners so that they can be correctly attributed to the activities they were involved in. The endpoint provides the ability to:

  • Retrieve all Practitioner resources that match a search criteria.
  • Retrieve one or more Practitioner resources based on their resource ID.
  • Retrieve the history of a Practitioner resource based on its resource ID, and optionally a version history.

This API is based on the R4 release of the FHIR standard, for more information on this API refer to the official FHIR documentation.

Methods

Retrieve Practitioners

GET /fhir/4.0/Practitioner/

This method returns details of practitioners that match the supplied search criteria, using the GET method. Practitioner searches may be performed by supplying one of the following minimum criteria. Either:

  • __id_, or
  • identifier, or
  • At least name, or given or family with zero (or more) of the following optional filters:
    • name
    • given
    • family
    • address-city
    • address-state
    • qualification

Parameters

Name

Type

Data Type

Description

Name:

_id

optional

Type:

query

Data Type:

array

Description:

The id of the Practitioner resource. A comma separated list of resource ids can be used to retrieve multiple practitioners. This parameter cannot be combined with other search parameters (e.g. name, qualification, ...) in a single request.


Sample Value: sha2EBMF4OQ6UIAKRRFWEHZXGGZMWZRWOODMEDOIZSZ5QG6SGF2K4JA

Name:

identifier

optional

Type:

query

Data Type:

array

Description:

The identifier for the practitioner which consists of practitioner identifier namespace, also known as the system, and identifier, separated using a URL encoded | character i.e. %7c. A comma separated list of identifiers can be used to search for multiple practitioners. This parameter cannot be combined with other search parameters (e.g. name, qualification, ...) in a single request.


Sample Value: clinical-portal-user|demo.provider

Name:

name

optional

Type:

query

Data Type:

string

Description:

Fragment of either family or given name of the Practitioner to search for. At least one of the family, given, and name parameters is required.


Sample Value: Dr John Doe

Name:

given

optional

Type:

query

Data Type:

string

Description:

A portion of the given name. At least one of the family, given, and name parameters is required.


Sample Value: demo

Name:

family

optional

Type:

query

Data Type:

string

Description:

A portion of the family name. At least one of the family, given, and name parameters is required.


Sample Value: provider

Name:

address-city

optional

Type:

query

Data Type:

string

Description:

A city specified in an address of the Practitioner to search for


Sample Value: Latrobe

Name:

address-state

optional

Type:

query

Data Type:

string

Description:

A state specified in an address of the Practitioner to search for


Sample Value: PA

Name:

qualification

optional

Type:

query

Data Type:

string

Description:

Practitioner's qualification (obtained by training or certification) to search for. A text based search is supported when appending the :text modifier to the parameter name (qualification:text). Otherwise, a combined <system>|<code> value is expected. The system part of the value is optional.


Sample Value: qualification-coding-system|qualification-code

Name:

-include-sources

optional

Type:

query

Data Type:

array

Description:

The -include-sources parameter defines which sources should be queried for the results.

Note: Either -include-sources or -exclude-sources parameter can be specified, not both. If -include-sources is specified, ONLY the specified sources will be searched. Note that the sources specified should be enabled.


Sample Value: -include-sources=SOURCEA

Name:

-exclude-sources

optional

Type:

query

Data Type:

array

Description:

The -exclude-sources parameter defines which sources should NOT be queried for the results.

Note: Either -include-sources or -exclude-sources parameter can be specified, not both. If -exclude-sources is specified, the specified sources will NOT be searched. Note that the sources specified should be enabled.


Sample Value: -exclude-sources=SOURCEA,SOURCEB

Name:

_summary

optional

Type:

query

Data Type:

string

Description:

Instructs the server to return a subset of the resource, reducing the size of the reponse payload. Possible values are

  • true: return summaries only
  • false: return full resources
  • count: return the count of search matches
  • text: return only the text, id, meta, and top-level mandatory elements
  • data: remove the text element


Sample Value: true

Name:

_elements

optional

Type:

query

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=identifier,active,name,_elements:exclude=*.extension,*.photo

Name:

-cursor

optional

Type:

query

Data Type:

string

Description:

A server internal parameter to navigate different pages.

This parameter is returned by the server as part of the Bundle 'next' link of a paginated query. And is used to retrieve the next page

Note: -cursor is applicable only for identifier search and demographics search (not applicable to search by _ids)


Name:

_count

optional

Type:

query

Data Type:

integer

Description:

Limit the number of match results to the specified _count. When _count is specified, the query will be paginated, and only _count or less results will be returned.

The returned bundle may contain a next link if more results could be available.

Note: _count is applicable only for identifier search and demographics search (not applicable to search by _ids)


Sample Value: 30

Name:

_sort

optional

Type:

query

Data Type:

array

Description:

Request which order results should be returned in.

Supported _sort parameters are:

  • name to sort by Practitioner.name ascending
  • -name to sort by Practitioner.name descending
  • active to sort by Practitioner.active ascending
  • -active to sort by Practitioner.active descending
  • _lastUpdated to sort by Practitioner.Meta.lastUpdated ascending
  • -_lastUpdatedto sort by Practitioner.Meta.lastUpdated descending

You can use any combination of the parameters

Note: _sort is applicable only for identifier search and demographics search (not applicable to search by _ids)


Default Value: -active,name

Sample Value: _sort=-active,name, -_lastUpdated

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

Specifies the language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

Name:

_format

optional

Type:

query

Data Type:

string

Description:

Media type of the response. It takes precedence over the Accept header. Possible values are json and xml.


Default Value: json

Sample Value: json

Name:

_pretty

optional

Type:

query

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Responses

application/json+fhir

200

Returns a FHIR Bundle containing 0..* OperationOutcome resources and 0..* Practitioner resources

application/json+fhir

400

This code is returned when the query contains one or more invalid parameters, e.g using incorrectly formatted identifiers.

Sample Requests

Search by Practitioner name
curl -X GET "https://developer-solution/fhir/4.0/Practitioner?name=Dr John Doe" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Retrieve Practitioners

POST /fhir/4.0/Practitioner/_search

This method returns details of practitioners that match the supplied search criteria, using the POST method. Practitioner searches may be performed by supplying one of the following minimum criteria. Either:

  • __id_, or
  • identifier, or

  • At least name, or given or family with zero (or more) of the following optional filters:

    • name
    • given
    • family
    • address-city
    • address-state
    • qualification

    This is the secure alternative to the GET search.

Parameters

Name

Type

Data Type

Description

Name:

Content-Type

required

Type:

header

Data Type:

string

Description:

Specifies how to encode the form data. The Content-Type value must be application/x-www-form-urlencoded


Sample Value: application/x-www-form-urlencoded

Name:

_id

optional

Type:

formData

Data Type:

array

Description:

The id of the Practitioner resource. A comma separated list of resource ids can be used to retrieve multiple practitioners. This parameter cannot be combined with other search parameters (e.g. name, qualification, ...) in a single request.


Sample Value: sha2EBMF4OQ6UIAKRRFWEHZXGGZMWZRWOODMEDOIZSZ5QG6SGF2K4JA

Name:

identifier

optional

Type:

formData

Data Type:

array

Description:

The identifier for the practitioner which consists of practitioner identifier namespace, also known as the system, and identifier, separated using a URL encoded | character i.e. %7c. A comma separated list of identifiers can be used to search for multiple practitioners. This parameter cannot be combined with other search parameters (e.g. name, qualification, ...) in a single request.


Sample Value: clinical-portal-user|demo.provider

Name:

name

optional

Type:

formData

Data Type:

string

Description:

Fragment of either family or given name of the Practitioner to search for. At least one of the family, given, and name parameters is required.


Sample Value: Dr John Doe

Name:

given

optional

Type:

formData

Data Type:

string

Description:

A portion of the given name. At least one of the family, given, and name parameters is required.


Sample Value: demo

Name:

family

optional

Type:

formData

Data Type:

string

Description:

A portion of the family name. At least one of the family, given, and name parameters is required.


Sample Value: provider

Name:

address-city

optional

Type:

formData

Data Type:

string

Description:

A city specified in an address of the Practitioner to search for


Sample Value: Latrobe

Name:

address-state

optional

Type:

formData

Data Type:

string

Description:

A state specified in an address of the Practitioner to search for


Sample Value: PA

Name:

qualification

optional

Type:

formData

Data Type:

string

Description:

Practitioner's qualification (obtained by training or certification) to search for. A text based search is supported when appending the :text modifier to the parameter name (qualification:text). Otherwise, a combined <system>|<code> value is expected. The system part of the value is optional.


Sample Value: qualification-coding-system|qualification-code

Name:

-include-sources

optional

Type:

formData

Data Type:

array

Description:

The -include-sources parameter defines which sources should be queried for the results.

Note: Either -include-sources or -exclude-sources parameter can be specified, not both. If -include-sources is specified, ONLY the specified sources will be searched. Note that the sources specified should be enabled.


Sample Value: -include-sources=SOURCEA

Name:

-exclude-sources

optional

Type:

formData

Data Type:

array

Description:

The -exclude-sources parameter defines which sources should NOT be queried for the results.

Note: Either -include-sources or -exclude-sources parameter can be specified, not both. If -exclude-sources is specified, the specified sources will NOT be searched. Note that the sources specified should be enabled.


Sample Value: -exclude-sources=SOURCEA,SOURCEB

Name:

_summary

optional

Type:

formData

Data Type:

string

Description:

Instructs the server to return a subset of the resource, reducing the size of the reponse payload. Possible values are

  • true: return summaries only
  • false: return full resources
  • count: return the count of search matches
  • text: return only the text, id, meta, and top-level mandatory elements
  • data: remove the text element


Sample Value: true

Name:

_elements

optional

Type:

formData

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=identifier,active,name,_elements:exclude=*.extension,*.photo

Name:

-cursor

optional

Type:

formData

Data Type:

string

Description:

A server internal parameter to navigate different pages.

This parameter is returned by the server as part of the Bundle 'next' link of a paginated query. And is used to retrieve the next page

Note: -cursor is applicable only for identifier search and demographics search (not applicable to search by _ids)


Name:

_count

optional

Type:

formData

Data Type:

integer

Description:

Limit the number of match results to the specified _count. When _count is specified, the query will be paginated, and only _count or less results will be returned.

The returned bundle may contain a next link if more results could be available.

Note: _count is applicable only for identifier search and demographics search (not applicable to search by _ids)


Sample Value: 30

Name:

_sort

optional

Type:

formData

Data Type:

array

Description:

Request which order results should be returned in.

Supported _sort parameters are:

  • name to sort by Practitioner.name ascending
  • -name to sort by Practitioner.name descending
  • active to sort by Practitioner.active ascending
  • -active to sort by Practitioner.active descending
  • _lastUpdated to sort by Practitioner.Meta.lastUpdated ascending
  • -_lastUpdatedto sort by Practitioner.Meta.lastUpdated descending

You can use any combination of the parameters

Note: _sort is applicable only for identifier search and demographics search (not applicable to search by _ids)


Default Value: -active,name

Sample Value: _sort=-active,name, -_lastUpdated

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

Specifies the language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

Name:

_format

optional

Type:

formData

Data Type:

string

Description:

Media type of the response. It takes precedence over the Accept header. Possible values are json and xml.


Default Value: json

Sample Value: json

Name:

_pretty

optional

Type:

formData

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Responses

application/json+fhir

200

Returns a FHIR Bundle containing 0..* OperationOutcome resources and 0..* Practitioner resources

application/json+fhir

400

This code is returned when the query contains one or more invalid parameters, e.g using incorrectly formatted identifiers.

Sample Requests

Search by Practitioner name
curl -X POST "https://developer-solution/fhir/4.0/Practitioner/_search" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8=' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'name=Dr John Doe'

Retrieve Practitioner(s) by ID(s)

GET /fhir/4.0/Practitioner/{id}

This method returns one or more Practitioner resources matching the requested resource IDs.

Parameters

Name

Type

Data Type

Description

Name:

id

required

Type:

path

Data Type:

string

Description:

The id of the Practitioner resource, can be a comma separated list of IDs for one or more practitioners.


Sample Value: shaJI3AP2T53AKS3RFNOCPPQHKP7C6MTOGPWRWWSCWODQ7HNPHXHDLA

Name:

_elements

optional

Type:

query

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=identifier,active,name,_elements:exclude=*.extension,*.photo

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

Specifies the language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

Name:

_format

optional

Type:

query

Data Type:

string

Description:

Media type of the response. It takes precedence over the Accept header. Possible values are json and xml.


Default Value: json

Sample Value: json

Name:

_pretty

optional

Type:

query

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Responses

application/json+fhir

200

Returns a Practitioner resource matching the requested resource ID.

application/json+fhir

400

This code is returned when the resource ID is empty.

application/json+fhir

404

No Practitioner resource found with the requested resource ID or the resource ID is invalid.

application/json+fhir

422

The practitioner ID is not in the correct format.

Sample Requests

Search by Practitioner ID
curl -X GET "https://developer-solution/fhir/4.0/Practitioner/shaJI3AP2T53AKS3RFNOCPPQHKP7C6MTOGPWRWWSCWODQ7HNPHXHDLA" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Retrieve a Practitioner's history

GET /fhir/4.0/Practitioner/{id}/_history

This method returns the change history for a Practitioner resource matching the requested resource ID. Practitioner resources can be retrieved from multiple data sources, and not all sources are able to return history information. This operation will return an empty set of data if no versions of the specified Practitioner can be found, which includes cases where:

  • The specified Practitioner resource cannot be found.
  • The data source for the Practitioner is unable to return history information.

Parameters

Name

Type

Data Type

Description

Name:

id

required

Type:

path

Data Type:

string

Description:

The id of the Practitioner resource


Sample Value: shaJI3AP2T53AKS3RFNOCPPQHKP7C6MTOGPWRWWSCWODQ7HNPHXHDLA

Name:

_elements

optional

Type:

query

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=identifier,active,name,_elements:exclude=*.extension,*.photo

Name:

_format

optional

Type:

query

Data Type:

string

Description:

Media type of the response. It takes precedence over the Accept header. Possible values are json and xml.


Default Value: json

Sample Value: json

Name:

_pretty

optional

Type:

query

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

Specifies the language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Responses

application/json+fhir

200

A FHIR Bundle containing 1..* Practitioner resources matching the requested resource ID.

application/json+fhir

400

  • The source providing the Practitioner resource is not capable of returning history of Practitioner resources.

application/json+fhir

404

  • No Practitioner resource found with the requested resource ID.

Sample Requests

Retrieve the history of a Practitioner identified by a resource id
curl -X GET "https://developer-solution/fhir/4.0/Practitioner/shaJI3AP2T53AKS3RFNOCPPQHKP7C6MTOGPWRWWSCWODQ7HNPHXHDLA/_history" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Retrieve a specific version of a Practitioner

GET /fhir/4.0/Practitioner/{id}/_history/{versionid}

This method returns a specific version of the Practitioner resource matching the requested resource ID. Practitioner resources can be retrieved from multiple data sources. This operation will return an empty set of data if no versions of the specified Practitioner can be found, which includes cases where:

  • The specified Practitioner resource cannot be found.

Parameters

Name

Type

Data Type

Description

Name:

id

required

Type:

path

Data Type:

string

Description:

The id of the Practitioner resource


Sample Value: shaBFKLMDEIT5PYYZ7WPTOULUGF3EUTBNLX4FL433XC6FGU7J566OPA

Name:

versionid

required

Type:

path

Data Type:

integer

Description:

The version of the Practitioner resource


Sample Value: 1

Name:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

Specifies the language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

_elements

optional

Type:

query

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=identifier,active,name,_elements:exclude=*.extension,*.photo

Name:

_format

optional

Type:

query

Data Type:

string

Description:

Media type of the response. It takes precedence over the Accept header. Possible values are json and xml.


Default Value: json

Sample Value: json

Name:

_pretty

optional

Type:

query

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Responses

application/json+fhir

200

Returns a Practitioner resource matching the the requested resource ID and version id.

application/json+fhir

400

  • The source providing the Practitioner resource is not capable of returning history of Practitioner resources.

application/json+fhir

404

  • No Practitioner resource found with the requested resource ID.
  • The version id specified does not exist for the Practitioner resource with the requested resource ID.

Sample Requests

Retrieve the version of Practitioner identified by a resource id and a version id
curl -X GET "https://developer-solution/fhir/4.0/Practitioner/shaBFKLMDEIT5PYYZ7WPTOULUGF3EUTBNLX4FL433XC6FGU7J566OPA/_history/1" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='