1.0.0 - release
NJSAMS - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
The FHIR server supports the CapabilityStatement resource, which describes the server's capabilities and supported operations. The capability statement is publicly available at the following URL: https://fhir.njsams.rutgers.edu/NJSAMS-FHIR-API/metadata?_format=application/json
The API supportings search , read, create, and update operations.
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. 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 Appscope
: openid fhirUser user/*.read
aud
: https://fhir.njsams.rutgers.edu/NJSAMS-FHIR-API
The OpenID Connect configuration is available at the following URL:
The SMART on FHIR configuration is available at the following URL:
The FHIR server uses security labels to protect sensitive information. The server supports the following security labels: https://fhir.njsams.rutgers.edu/NJSAMS-fhir/fhir/security/provider-id
Every resource must be tagged with a security label. The server will return a 403 Forbidden error if the resource does not have the required security label.
The FHIR server supports Single Sign-On (SSO) using the OpenID Connect protocol. External identity providers (IdPs) such as Microsoft Entra, Okta, and Auth0 can be used to authenticate users. The FHIR server will redirect users to the IdP for authentication, and upon successful authentication, the IdP will redirect the user back to the FHIR server with an authorization code.
IdPs SHALL include a unique identifier as an OIDC claim for each user: https://www.hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html#scopes-for-requesting-identity-data.
Ideally, the IdP SHOULD include the fhirUser
scope in the OIDC claims. This scope is used to identify the user in the FHIR server and is required for accessing protected resources.
Support for asymmetric clients using JWKs is also available. This allows clients to authenticate using public/private key pairs instead of client secrets. If a client wants to hosts its own JWKs, it can provide NJSAMS with a JWKs URL. The FHIR server will use this URL to retrieve the JWKs and verify the client's signature.
Please contact NJSAMS for more information on setting up SSO with your IdP.
There is a non-production NJSAMS FHIR sandbox server with anonymized example data for testing.
This Sandbox requires authentication. The {server-base}
for the sandbox is:
The SMART on FHIR configuration for the sandbox is available at:
The URL for the Sandbox authorization server is:
The OpenID Connect configuration for the sandbox is available at:
The patient resource represents a client and includes demographics and contact information.
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",
"meta": {
"profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSPatient"]
}
// ...
}
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
]
}
An encounter represents a vist for a client, including the location and length of stay.
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",
"meta": {
"profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSEncounter"]
}
// ...
}
See also
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
]
}
An coverage represents a a payor for a client
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",
"meta": {
"profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSCoverage"]
}
// ...
}
See also
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
]
}
⚠️ WARNING: Please be aware that FHIR resources created in NJSAMS will not be immediately available to read from the FHIR API. FHIR resources must be processed by NJSAMS before they are available to read. This may take at least 24 hours.
Only FHIR Bundles can be created or updated. The FHIR server does not support creating or updating individual resources.
Bundles are used to create or update multiple resources in a single request. The bundle must contain the resources to be created or updated, and the bundle type must be set to transaction
.
The bundle must also contain a Bundle.entry.request
element for each resource to be created or updated. The method
field must be set to POST
for creating resources and PUT
for updating resources. The url
field must be set to the resource type and logical ID of the resource being created or updated.
To create a bundle, provide the bundle contents in the request body. The bundle must be of type transaction
and contain the resources to be created.
Request abstract
POST [server-base]/Bundle
Content-Type: application/json+fhir
Accept: application/json+fhir
Authorization: Bearer {bearer-token}
Request example
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:8d5802a8-14ea-4198-ba0d-bd1884e63053",
"resource": {
"resourceType": "Patient",
"meta": {
"profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSPatient"],
"security": [
{
"system": "https://fhir.njsams.rutgers.edu/NJSAMS-fhir/fhir/security/provider-id",
"code": "123456"
}
]
},
// ...
},
"request": {
"method": "POST",
"url": "Patient"
}
}
]
}
Response example
{
"resourceType": "Bundle",
"id": "8d5802a8-14ea-4198-ba0d-bd1884e63053",
"type": "transaction-response",
"entry": [
{
"response": {
"status": "201 Created",
"location": "[server-base]/Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053"
}
}
]
}
To update a bundle, provide the bundle contents in the request body. The bundle must be of type transaction
and contain the resources to be updated.
The bundle must also contain a Bundle.entry.request
element for each resource to be updated. The method
field must be set to PUT
for updating resources. The url
field must be set to the resource type and logical ID of the resource being updated.
Request abstract
PUT [server-base]/Bundle
Content-Type: application/json+fhir
Accept: application/json+fhir
Authorization: Bearer {bearer-token}
Request example
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:8d5802a8-14ea-4198-ba0d-bd1884e63053",
"resource": {
"resourceType": "Patient",
"meta": {
"profile": ["https://fhir.njsams.rutgers.edu/NJSAMS-fhir/StructureDefinition/NJSAMSPatient"],
"security": [
{
"system": "https://fhir.njsams.rutgers.edu/NJSAMS-fhir/fhir/security/provider-id",
"code": "123456"
}
]
},
},
"request": {
"method": "PUT",
"url": "Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053"
}
}
]
}
Response example
{
"resourceType": "Bundle",
"id": "8d5802a8-14ea-4198-ba0d-bd1884e63053",
"type": "transaction-response",
"entry": [
{
"response": {
"status": "200 OK",
"location": "[server-base]/Patient/8d5802a8-14ea-4198-ba0d-bd1884e63053"
}
}
]
}