Search Relay Operation

Experimental

This is an early access feature and is subject to change.

OPERATION: POST [base]/[Resource]/$search-relay

The Search Relay operation is used to relay requests to another FHIR server.

Supported Resources

This operation has been implemented for the following resources:

• Location
• Organization

Workflow

Authorization

This operation will require the application obtain authorization to read the resource to relay using one of the following SMART clinical scopes.

• v1: [patient|user|system]/[Location|Organization].[read|*]
• v2: [patient|user|system]/[Location|Organization].[s] (future)

Parameters

Supported search parameters may vary by resource:

Location

Use	Name	Cardinality	Type	Documentation
IN	address	0..1	string	A (part of the) address of the location
IN	address-city	0..1	string	A city specified in an address
IN	address-postalcode	0..1	string	A postal code specified in an address
IN	address-state	0..1	string	A state specified in an address
IN	identifier	0..1	identifier	Any identifier for the organization (not the accreditation issuer's identifier)
IN	name	0..1	string	A portion of the organization's name or alias
IN	organization	0..1	reference	Searches for locations that are managed by the provided organization
IN	target-system	1..1	string	The unique ID assigned to the external FHIR server.

Organization

Use	Name	Cardinality	Type	Documentation
IN	address	0..1	string	A server defined search that may match any of the string fields in the Address, including line, city, district, state, country, postalCode, and/or text.
IN	address-city	0..1	string	A city specified in an address
IN	address-postalcode	0..1	string	A postal code specified in an address
IN	address-state	0..1	string	A state specified in an address
IN	identifier	0..1	identifier	Any identifier for the organization (not the accreditation issuer's identifier)
IN	name	0..1	string	A portion of the organization's name or alias
IN	target-system	1..1	string	The unique ID assigned to the external FHIR server.

Examples

Production

curl -X POST 'https://fhir.netsmartcloud.com/v4/Organization/$search-relay' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d @payload.json

Preview

curl -X POST 'https://fhirtest.netsmartcloud.com/v4/Organization/$search-relay' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d @payload.json

Payloads

Sample Search Relay Payload

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "name",
      "valueString": "Acme"
    },
    // Addition search parameters
    {
      "name": "target-system",
      "valueString": "ac97a53f-54cc-4d73-8f9a-ffae5f503d78"
    }
  ]
}

Sample Search Relay Response Payloads

Search Relay Success

{
  "resourceType": "Bundle",
  "id": "bfef1cc5-9204-465b-b910-a3d59430b97f",
  "type": "searchset",
  "total": 8,
  "entry": [
    {
      "fullUrl": "https://.../Organization/1",
      "resource": {
        // A matching Organization resource
      }
    },
    // Additional matches excluded for brevity
  ]
}

Invalid Search Relay Payload or Other Unprocessable Request

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "details": {
        "text": "Exception message"
      }
    }
  ]
}

Rejections or Other Search Relay Processing Errors

{
  "resourceType": "Parameters",
  "parameter": [
    // Search parameters
    {
      "name": "target-system",
      "valueString": "ac97a53f-54cc-4d73-8f9a-ffae5f503d78"
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "error",
            "code": "processing",
            "details": {
              "text": "status note"
            }
          }
        ]
      }
    }
  ]
}

Errors

Errors will be reported within an OperationOutcome and could include:

Issue	Description	HTTP Status
T.B.D.	T.B.D.	400 Bad Request
T.B.D.	T.B.D.	500 Internal Server Error
T.B.D.	T.B.D.	501 Not Implemented