Skip to main content

Resources

The Payer Provider Directory API supports a number of HL7 FHIR R4 resources. Each supported resource shares some characteristics in common.

Supported Headers​

HeaderDirectionDescription
AcceptRequestPreferred format of response payload.
Content-TypeResponseThe 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 Accept 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/payer/provider-directory/v2/{tenant-id}/{Resource}/{id} \
    -H "Accept: application/fhir+json"

Common Parameters​

NameTypeDescription
_countspecialInteger. Number of result to return per page. Default: 100. Max: 500
_offsetspecialInteger. Page offset (zero-based). Default: 0
_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/payer/provider-directory/v2/{tenant-id}/{Resource}/_search \
    -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/payer/provider-directory/v2/{tenant-id}/{Resource}?parameter=value&parameter=value" \
    -H "Accept: application/fhir+json"

Search Example​

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

Example: Patient Search by Family Name
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Practitioner/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "family=Baker%20_offset=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 7.0.2 REST Server (FHIR Server; FHIR 4.0.1/R4)
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.

403 Forbidden​

Access Denied.​
Example: Access Denied
HTTP/2 403
content-type: application/xml
date: Wed, 09 Oct 2024 21:30:02 GMT
server: AmazonS3
x-cache: Error from cloudfront
via: 1.1 813d4fdcf03ccb5c728fb2d996903bb4.cloudfront.net (CloudFront)
x-amz-cf-pop: LAX50-P2
alt-svc: h3=":443"; ma=86400
x-amz-cf-id: UKY3UdQXZN4dTwh-tVLVfAWnp1IBYHjGQtmTFAQ_pYFRbyMH4WJKHw==

<?xml version="1.0" encoding="UTF-8"?>
<Error><Code>AccessDenied</Code><Message>Access Denied</Message><RequestId>NN8YQGEWQSHWDNNV</RequestId><HostId>WKs7968i6tKOM2w4BOdDCgbo5PZgHlr0wo9LF0nDTuTyTP+evMg+H0Ksuqh+YY46nGqcgyQwvdE=</HostId></Error>

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/payer/provider-directory/invalid/{tenant-id}/Location/123456 \
     -H 'Accept: application/fhir+json'

404 Not Found​

A 404 Not Found response could be returned for a couple reasons.

The requested resource doesn't exist​
Example: Requested entity not found
HTTP/2 404
content-type: application/fhir+json;charset=UTF-8
content-length: 134
date: Wed, 09 Oct 2024 21:31:26 GMT
x-amzn-requestid: 9df458c1-a1b3-4edd-8f6d-0e62542732f2
strict-transport-security: max-age=31536000; includeSubDomains
x-amzn-remapped-connection: keep-alive
x-request-id: 79cf9364-f02b-446a-aebd-3797ed58ea63
x-amz-apigw-id: fZtnOG3EiYcESaA=
x-amzn-remapped-server: nginx
x-powered-by: HAPI FHIR 7.0.2 REST Server (FHIR Server; FHIR 4.0.1/R4)
x-ntst-transaction-id: 79cf9364-f02b-446a-aebd-3797ed58ea63
x-amzn-remapped-date: Wed, 09 Oct 2024 21:31:26 GMT
x-cache: Error from cloudfront
via: 1.1 8b7ef769fc2c91a0e16129302042a4c8.cloudfront.net (CloudFront)
x-amz-cf-pop: LAX50-P2
alt-svc: h3=":443"; ma=86400
x-amz-cf-id: oCoIGDNCwhA2JQLjVvewMiPcSVLt2tl_H2esI9XELwEGLdzUKYnUrQ==

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"not-found","details":{"text":"Requested entity not found."}}]}
The request was for an unsupported resource​
Example: Not Found
HTTP/2 404
content-type: application/fhir+json;charset=UTF-8
content-length: 301
date: Wed, 09 Oct 2024 21:32:56 GMT
x-amzn-requestid: c1f3e64d-1f7c-48e2-89de-4dd2152a4256
strict-transport-security: max-age=31536000; includeSubDomains
x-amzn-remapped-connection: keep-alive
x-request-id: ZpNMSdYMzf9DLkcm
x-amz-apigw-id: fZt1VGJQiYcELHw=
x-amzn-remapped-server: nginx
x-powered-by: HAPI FHIR 7.0.2 REST Server (FHIR Server; FHIR 4.0.1/R4)
x-amzn-remapped-date: Wed, 09 Oct 2024 21:32:56 GMT
x-cache: Error from cloudfront
via: 1.1 22970b0a8867d7ddc056c13511c8bfbc.cloudfront.net (CloudFront)
x-amz-cf-pop: LAX50-P2
alt-svc: h3=":443"; ma=86400
x-amz-cf-id: gCrir9sSMYAWEWrMQyIiLQ9AwpbQTfjQ9t00fIOPAYsGNKiAm-9wQQ==

{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"HAPI-0302: Unknown resource type 'Invalid' - Server knows how to handle: [Endpoint, HealthcareService, InsurancePlan, Location, Organization, OrganizationAffiliation, Practitioner, PractitionerRole]"}]}
curl -i https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Invalid/123456 \
     -H 'Accept: application/fhir+json'

500 Internal Server Error​

Example: Internal Server Error
HTTP/2 500 Internal Server Error
Date: Thu, 30 Nov 2023 14:59:17 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 131
Connection: keep-alive
x-amzn-RequestId: 135a33a5-41c2-44fd-8358-3da5ffe5b75e
Strict-Transport-Security: max-age=31536000; includeSubDomains
x-amzn-Remapped-Connection: keep-alive
X-Request-ID: df6f98f0-cce4-4ddb-8ce3-37b758e40026
x-amz-apigw-id: 33N5MEfvCYcEzZQ=
x-amzn-Remapped-Server: nginx
X-Powered-By: HAPI FHIR 7.0.2 REST Server (FHIR Server; FHIR 4.0.1/R4)
x-amzn-Remapped-Date: Thu, 30 Nov 2023 14:59:17 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 14:57:04 GMT
Content-Type: application/fhir+json;charset=UTF-8
Content-Length: 183
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 7.0.2 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 GetPDEndpointResource: GetPDEndpointResource Action not supported"}]}
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: 183
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 7.0.2 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 GetPDEndpointResource: GetPDEndpointResource Action not supported"}]}

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