Skip to main content

Resources

The Bulk Data Export API is built upon the Binary and Group resources. The primary workflow uses extended operations on these resources, yet we have made the standard Read operation available for testing and validation.

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​

Note: Supported content types are documented in the CapabilityStatement. Always verify current formats before implementation.

This API typically supports:

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

Supported Formats​

Note: Supported formats are extracted from the CapabilityStatement format array. Always verify current formats by retrieving the CapabilityStatement.

Typically supported formats include:

  • application/fhir+json - FHIR JSON format
  • application/fhir+xml - FHIR XML format
  • json - JSON format
  • xml - XML format

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/bulk-data/{Resource}/{id} \
    -H "Authorization: {Bearer token}" \
    -H "Content-Type: application/fhir+json"

Error Handling​

For comprehensive error scenarios, troubleshooting guidance, and common issues, see Common Errors.

Legacy Error Examples​

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/bulk-data/Group/1 \
     -H 'Content-Type: application/fhir+json'
No token in the Authorization Header of the request​
curl -i https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/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/bulk-data/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/bulk-data/Group/123456 \
     -H 'Authorization: Bearer {token}' \
     -H 'Content-Type: application/fhir+json' \
     -d @group.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/bulk-data/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 15:28:18 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 131
Connection: keep-alive
x-amzn-RequestId: 2a59c935-d629-4994-a1bf-b0e361b3bc4b
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: 89baf452-84be-4843-82c0-256c18fba2d3
x-amz-apigw-id: PN-C6GyBiYcEN-A=
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:28:18 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 15:30:12 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 163
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 GetAllergy: No instance for action GetAllergy"}]}
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: 159
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 GetBinary: GetBinary Action not supported"}]}

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