Search Devices by ID

The client can search for multiple Device resources by their FHIR IDs in a single request. The search can be performed either with a GET request or with a POST request, both of which are described below.

Each device in the result must belong to a patient for whom the requesting organization has a valid data-sharing consent. Devices for which consent is absent or access is otherwise denied are not omitted silently; instead, an OperationOutcome entry is included in the response Bundle for each such device.

Search using GET

The client provides a comma-separated list of FHIR IDs in the _id query parameter:

curl -sS "https://${server}/${basePath}/Device?_id=${device_fhir_id_1},${device_fhir_id_2}" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

Search using POST

Alternatively, the same search can be performed using a POST request with the parameters supplied as a URL-encoded form body:

curl -sS -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "_id=${device_fhir_id_1},${device_fhir_id_2}" \
  "https://${server}/${basePath}/Device/_search" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

Constraints

• The _id parameter is required. Omitting it results in a 400 Bad Request response.
• Each ID in the list must match the FHIR ID format [A-Za-z0-9\-.]{1,64}. An invalid ID results in a 400 Bad Request response.
• The maximum number of IDs that can be requested in a single call is 100. Exceeding this limit results in a 400 Bad Request response.

Response

The server responds with 200 OK and a FHIR R5 Bundle of type searchset. Each entry in the Bundle represents either a successfully retrieved device or an error for a specific requested ID:

• Successful entries have search.mode set to match and contain a Device resource. Each Device resource includes a definition field referencing the DeviceDefinition that describes its model. The referenced DeviceDefinition can be fetched using the Fetch DeviceDefinition by ID endpoint or retrieved in bulk using the Search DeviceDefinitions by ID endpoint.
• Error entries have search.mode set to outcome and contain an OperationOutcome resource with a description of the problem (e.g. the device was not found or access was denied).

Example response:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "/fhir/r5/Device?_id=37f8e876-d3ef-40ed-aaf4-795c3f88ce6c,unknown-id"
    }
  ],
  "entry": [
    {
      "resource": {
        "resourceType": "Device",
        "id": "37f8e876-d3ef-40ed-aaf4-795c3f88ce6c",
        "meta": {
          "profile": [
            "https://roche.com/fhir/iop/StructureDefinition/rdc-Device"
          ]
        },
        "definition": {
          "reference": {
            "reference": "DeviceDefinition/ed434a7c-8fd6-4382-ba7b-eccff3e6e07b"
          }
        },
        "serialNumber": "SN-1234"
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "error",
            "code": "not-found",
            "details": {
              "text": "Problem encountered with requested resource Device/unknown-id"
            }
          }
        ]
      },
      "search": {
        "mode": "outcome"
      }
    }
  ]
}

Error responses

Errors that apply to the request as a whole result in a non-200 HTTP status code:

Per-resource errors (device not found, access denied) are reported inline as OperationOutcome entries in the response Bundle rather than as a top-level HTTP error.

All error responses follow the FHIR OperationOutcome format described in Error Responses.