Skip to main content

Resources

The Certified Patient Access API supports a number of HL7 FHIR R4 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+json;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. 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/uscore/v1/{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/uscore/v1/{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/uscore/v1/{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/uscore/v1/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"

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/uscore/v1/Patient/1 \
     -H 'Content-Type: application/fhir+json'
No token in the Authorization Header of the request​
curl -i https://fhir.netsmartcloud.com/uscore/v1/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/uscore/v1/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/uscore/v1/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/uscore/v1/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 18:52:13 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 131
Connection: keep-alive
x-amzn-RequestId: df6f98f0-cce4-4ddb-8ce3-37b758e40026
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: a9230d3c-17bc-4767-b127-d469a69c7566
x-amz-apigw-id: PObn0DB6iYcVSzw=
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 18:52:13 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: Not Implemented
HTTP/2 501 Not Implemented
Date: Thu, 30 Nov 2023 18:50:13 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 205
Connection: keep-alive
x-amzn-RequestId: 786e979e-91ad-442d-98be-fdd6b030f23e
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: 09988585-b7d7-4f15-900f-ae761f69eeb3
x-amz-apigw-id: PObn1FB6iYcEZng=
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 18:50:13 GMT

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"Failed to call GetExplanationOfBenefitResource: No instance for action GetExplanationOfBenefitResource"}]}
Example: Action not supported
HTTP/2 501 Not Implemented
Date: Thu, 30 Nov 2023 15:30:12 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 203
Connection: keep-alive
x-amzn-RequestId: 78ec3f07-aa0c-4c35-805d-e8ab590c17dc
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: ec5bb9bf-ad48-491c-a19c-f35374ab2dbc
x-amz-apigw-id: MN5dXzjEQYcEUZQ=
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 15:30:12 GMT

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

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