Skip to main content

Resources

The General Purpose FHIR STU3 endpoint supports a number of resources. Each supported resource shares some characteristics in common.

Supported Headers​

HeaderDirectionDescription
AuthorizationRequestRequired. Includes bearer token to authorize the request.
Content-TypeRequest & ResponsePreferred format of response payload.
Default: application/fhir+xml;charset=UTF-8
X-Correlation-IdResponseUsed to provide the requester’s transaction ID back in the response when it is not accepted as the transaction ID for Netsmart logging.
X-Request-IDRequest & ResponseUnique transaction ID for logging purposes. Typically, a UUID.
If this header is passed in the request Netsmart will either accept it as the transaction ID or return it in the response X-Correlation-Id header.

Content-Type​

This API supports accepting and returning resources as XML and JSON. This API defaults to XML to support constraints of some of our early adopters. You can specify your preference by using the Content-Type header.

JSONXML
application/fhir+jsonapplication/fhir+xml
application/jsonapplication/xml

Operations​

Resources on this endpoint will support one or more of the following operations. This section describes how to implement each operation. Please consult the resource-specific documentation to determine which operations are supported.

Read​

curl -X GET https://fhir.netsmartcloud.com/fhir/{Resource}/{id} \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json"

Common Parameters​

NameTypeDescription
pagestringPage index (one-based). Default: 1
_countspecialInteger. Number of result to return per page. Default: 100. Max: 500
_sortspecialSortSpec. Sort option.

Via POST (recommended)​

The POST method is recommended as it keeps health information out of the URL.

curl -X POST https://fhir.netsmartcloud.com/fhir/{Resource}/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "parameter=value%20parameter=value"

Via GET​

curl -X GET "https://fhir.netsmartcloud.com/fhir/{Resource}?parameter=value&parameter=value" \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json"

Search Example​

The following example illustrates using the common search parameters with the Patient resource. The API will return the second set of 5 matching results for Patients with the family name like "Baker".

Example: Patient Search by Family Name
curl -X POST https://fhir.netsmartcloud.com/fhir/Patient/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "family=Baker%20page=2%20_count=5"

Create​

curl -X POST https://fhir.netsmartcloud.com/fhir/{Resource} \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d @resource.json

Update​

curl -X PUT https://fhir.netsmartcloud.com/fhir/{Resource}/{id} \
    -H "Authorization: {Bearer token}" \
    -H "Content-Type: application/fhir+json" \
    -d @resource.json

Common Errors​

By HTTP Status Code​

400 Bad Request​

HTTP/2 400 Bad Request
Date: Fri, 05 May 2023 15:48:18 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 149
Connection: keep-alive
x-amzn-RequestId: fe94d584-6167-41cc-9210-775ae7e02d5f
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: f44edc90-ece1-425c-b3f3-d854f0ec8ebb
x-amz-apigw-id: EdLCTESAiYcFmRg=
x-amzn-Remapped-Server: nginx
X-Powered-By: HAPI FHIR 5.7.6 REST Server (FHIR Server; FHIR 4.0.1/R4)
X-NTST-App-Version: NTST-FHIR-v1.1.15-SNAPSHOT_2023-04-18T21:33:58.540962451Z_2023-04-18T21:33:58.525072381Z
x-amzn-Remapped-Date: Fri, 05 May 2023 15:48:18 GMT

{"resourceType":"OperationOutcome","issue":[{"severity":"warning","code":"processing","diagnostics":"{description of error}"}]}

Reasons for this response may vary. You will need to read the OperationOutcome for more information.

401 Unauthorized​

UnauthorizedException​
Example: UnauthorizedException
HTTP/2 401 Unauthorized
Date: Fri, 05 May 2023 16:14:14 GMT
Content-Type: application/json
Content-Length: 26
Connection: keep-alive
x-amzn-RequestId: 78531155-b16c-4fcc-b27d-2dee6c9f9fd2
x-amzn-ErrorType: UnauthorizedException
x-amz-apigw-id: EdO1lGPrCYcFdvg=

{"message":"Unauthorized"}

You will typically see this response when one of the following occurs:

No Authorization Header in the request​
curl -i https://fhir.netsmartcloud.com/fhir/Patient/1 \
     -H 'Content-Type: application/fhir+json'
No token in the Authorization Header of the request​
curl -i https://fhir.netsmartcloud.com/fhir/Patient/1 \
     -H 'Authorization: ' \
     -H 'Content-Type: application/fhir+json'

403 Forbidden​

AccessDeniedException​
Example: AccessDeniedException
HTTP/2 403 Forbidden
Date: Fri, 05 May 2023 16:12:43 GMT
Content-Type: application/json
Content-Length: 82
Connection: keep-alive
x-amzn-RequestId: 27ce6e0d-f2fd-44c4-a165-49c176e2afe3
x-amzn-ErrorType: AccessDeniedException
x-amz-apigw-id: EdOnXGqtCYcF7IA=

{"Message":"User is not authorized to access this resource with an explicit deny"}

You will typically see this response when one of the following occur:

  • An invalid Bearer token is provided with the request.
  • An expired Bearer token is provided with the request.
IncompleteSignatureException​
Example: IncompleteSignatureException
HTTP/2 403 Forbidden
Date: Fri, 05 May 2023 16:37:55 GMT
Content-Type: application/json
Content-Length: 2994
Connection: keep-alive
x-amzn-RequestId: 4f29af98-da15-43c9-81ee-2f8984f27d1f
x-amzn-ErrorType: IncompleteSignatureException
x-amz-apigw-id: EdSTiHl0iYcFeCw=

# Possible Payload #1
{"message":"Authorization header requires 'Credential' parameter. Authorization header requires 'Signature' parameter. Authorization header requires 'SignedHeaders' parameter. Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header. Authorization={malformedBearerToken}"}

# Possible Payload #2
{"message":"'{bearerToken}' not a valid key=value pair (missing equal-sign) in Authorization header: 'Bearer {bearerToken}'."}

You will typically see this response when one of the following occur:

The request was sent to an invalid path​
curl -i https://fhir.netsmartcloud.com/fhir/Invalid/123456 \
     -H 'Authorization: Bearer {token}' \
     -H 'Content-Type: application/fhir+json'
The request was sent using an unsupported HTTP Verb​
curl -i -X PATCH https://fhir.netsmartcloud.com/fhir/Patient/123456 \
     -H 'Authorization: Bearer {token}' \
     -H 'Content-Type: application/fhir+json' \
     -d @patient.json
MissingAuthenticationTokenException​
Example: MissingAuthenticationTokenException
HTTP/2 403 Forbidden
Date: Fri, 05 May 2023 16:29:44 GMT
Content-Type: application/json
Content-Length: 42
Connection: keep-alive
x-amzn-RequestId: 5e6e468d-f7a2-4aec-a320-630734e12a6e
x-amzn-ErrorType: MissingAuthenticationTokenException
x-amz-apigw-id: EdRG8Ho1CYcFqUQ=

{"message":"Missing Authentication Token"}

You will typically see this response when the request was sent to an invalid path and without an Authorization Header.

curl -i https://fhir.netsmartcloud.com/fhir/Invalid/123456 \
     -H 'Content-Type: application/fhir+json'

404 Not Found​

HTTP/2 404 Not Found
Date: Fri, 05 May 2023 15:58:54 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 150
Connection: keep-alive
x-amzn-RequestId: 5189c850-e6cf-4d2c-b97f-34ae0962b8d1
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: f7d745cf-0c94-4e41-b641-7945740c922c
x-amz-apigw-id: EdMlqGfZCYcFp7g=
x-amzn-Remapped-Server: nginx
X-Powered-By: HAPI FHIR 5.7.6 REST Server (FHIR Server; FHIR 4.0.1/R4)
x-amzn-Remapped-Date: Fri, 05 May 2023 15:58:54 GMT

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"HAPI-0436: Resource Patient/123456 is not known"}]}

500 Internal Server Error​

Example: Internal Server Error
HTTP/2 500 Internal Server Error
Date: Thu, 30 Nov 2023 19:33:35 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 131
Connection: keep-alive
x-amzn-RequestId: dd7cd58a-8c3d-4fec-ba8e-5cbb3e467fa0
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: e1c37ff0-212c-4d78-a1d8-746d56ea7057
x-amz-apigw-id: LSbn0BAZasYcVSzw=
x-amzn-Remapped-Server: nginx
X-Powered-By: HAPI FHIR 5.7.6 REST Server (FHIR Server; FHIR 4.0.1/R4)
x-amzn-Remapped-Thu, 30 Nov 2023 19:33:35 GMT

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"An unexpected error occurred"}]}

You will typically see this response when the server has encountered an unexpected condition that prevented it from fulfilling the request.

501 Not Implemented​

Example: No instance for action
HTTP/2 501 Not Implemented
Date: Thu, 30 Nov 2023 19:31:45 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 163
Connection: keep-alive
x-amzn-RequestId: 49fcb196-9b59-47bc-a6be-d98f6e9d2d31
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: 976673e7-812d-49e7-802f-efe3e82413a0
x-amz-apigw-id: CVawFB6iYcEZig=
x-amzn-Remapped-Server: nginx
X-Powered-By: HAPI FHIR 5.7.6 REST Server (FHIR Server; FHIR 4.0.1/R4)
x-amzn-Remapped-Thu, 30 Nov 2023 19:31:45 GMT

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"Failed to call GetAllergy: No instance for action GetAllergy"}]}
Example: Action not supported
HTTP/2 501 Not Implemented
Date: Thu, 30 Nov 2023 14:57:04 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 161
Connection: keep-alive
x-amzn-RequestId: 86da5d9c-02bf-48fb-b814-5a29e22539a4
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: e6734305-a118-4f46-a549-be1d06ec99f8
x-amz-apigw-id: PN5dMEMvCYcEUZQ=
x-amzn-Remapped-Server: nginx
X-Powered-By: HAPI FHIR 5.7.6 REST Server (FHIR Server; FHIR 4.0.1/R4)
x-amzn-Remapped-Date: Thu, 30 Nov 2023 14:57:04 GMT

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"Failed to call GetAllergy: GetAllergy Action not supported"}]}

You will typically see these responses when the server does not recognize or support the functionality required to fulfill the request.

Special Considerations​

Datatype Handling​

Address​

When submitting a resource (i.e., create or update) that contains an Address the following constraints apply:

  1. Address.use has limited support. Recommendation is to use our Certified API or General Purpose R4 API instead.
  2. Address.type is not supported.

ContactPoint (a.k.a., telecom)​

When submitting a resource (i.e., create or update) that contains a ContactPoint entry the following constraints apply:

  1. ContactPoint.system is constrained to phone. Other codes are unsupported.
  2. ContactPoint.use has limited support. Recommendation is to use our Certified API or General Purpose R4 API instead.