FHIR Implementation Guide for NJSAMS


0.1.0 - draft New Jersey

NJSAMS - Local Development build (v0.1.0). See the Directory of published versions

API

The API is read-only, supporting search and read operations.

See capabilities and swagger/OpenAPI documentation

Authorization (Production FHIR Server)

The FHIR server endpoint is protected. Third-party applications (Apps) can ask the resource owner (a User) for permission to access protected resources on their behalf. The server implements OAuth2 and SMART on FHIR standards, which describe how the App can ask the User for such permission.

Before an App can run against the FHIR API, it must be registered with the NJSAMS authorization server ([TBD, put the URL here]). Every registered App receives its client_id and client_secret. Please contact NJSAMS for getting access.

In addition to the parameters specified in the SMART on FHIR documentation, the Apps must use the following parameters when making a request to the /authorize endpoint:

  • response_type: code
  • redirect_uri: any of the redirect_uri values communicated to NJSAMS when registering the App
  • scope: openid fhirUser user/*.read
  • aud: [TBD, the address of the FHIR server API]

Sandbox (Open Endpoint)

There is a non-production NJSAMS FHIR sandbox server with anonymized example data for testing. This server does not require authentication (so the Authorization header below is not required). The {server-base} for the sandbox is:

https://fhir.njsams.rutgers.edu/sandbox

Read and Search: Patient

The patient resource represents a client and includes demographics and contact information.

Read

To read a patient, provide the patient’s Logical ID.

Request abstract

GET [server-base]/Patient/:logical-id
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Request with a fake logical-id

GET [server-base]/Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response example

{
  "resourceType": "Patient",
  "id": "8d5802a8-14ea-4198-ba0d-bd1884e63053",
  // ...
}

See also

To search patients, provide patient search criteria

Search

GET [server-base]/Patient?:search-criteria
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for patients with family name “smith”

GET [server-base]/Patient?family=smith
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for patients with client identifier “12345”

GET [server-base]/Patient?identifier=12345
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response

The response is a FHIR Bundle containing the matching patients:

{
  "resourceType": "Bundle",
  "type": "search-result",
  "entry": [
    // ... Patient resources
  ]
}



Read and Search: Encounter

An encounter represents a vist for a client, including the location and length of stay.

Read

To read an encounter, provide the encounters’s Logical ID.

Request abstract

GET [server-base]/Encounter/:logical-id
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Request with a fake logical-id

GET [server-base]/Encounter/9c9ee5c7-f972-4b19-8e68-07b8b95cfe4e
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response example

{
  "resourceType": "Encounter",
  "id": "9c9ee5c7-f972-4b19-8e68-07b8b95cfe4e",
  // ...
}

See also

Search

To search encounters, provide encounter search criteria

Search

GET [server-base]/Encounter?:search-criteria
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for encounters for a known patient

GET [server-base]/Encounter?subject=Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for encounters overlapping a specified date

GET [server-base]/Encounter?date=2022-01-01
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for all encounters and include the patient in response

GET [server-base]/Encounter?_include=Encounter:subject
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response

The response is a FHIR Bundle containing the matching patients:

{
  "resourceType": "Bundle",
  "type": "search-result",
  "entry": [
    // ... Encounter resources
  ]
}



Read and Search: Coverage

An coverage represents a a payor for a client

Read

To read a coverage, provide the coverage’s Logical ID.

Request abstract

GET [server-base]/Coverage/:logical-id
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Request with a fake logical-id

GET [server-base]/Coverage/d06175bc-1513-4831-ab3f-9f23b019a6c1
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response example

{
  "resourceType": "Coverage",
  "id": "d06175bc-1513-4831-ab3f-9f23b019a6c1",
  // ...
}

See also

Search

To search coverage, provide coverage search criteria

Search

GET [server-base]/Coverage?:search-criteria
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for coverages for a known patient

GET [server-base]/Coverage?beneficiary=Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Search for coverages by payor organization

GET [server-base]/Coverage?payor=Organization/1r566il9-14ea-4198-ba0d-bd1884e63053
Accept: application/json+fhir
Authorization: Bearer {bearer-token}

Response

The response is a FHIR Bundle containing the matching patients:

{
  "resourceType": "Bundle",
  "type": "search-result",
  "entry": [
    // ... Coverage resources
  ]
}