Testing FHIR Provider Directory with Postman

This tutorial walks you through setting up Postman to test FHIR Payer Provider Directory APIs in the Preview environment. You'll learn to create environments, configure collections, and make API requests to access provider network information including organizations, practitioners, and locations.

Important: This tutorial uses the Preview environment with test data. The Provider Directory APIs do not contain patient health information and are publicly accessible without authentication.

Prerequisites

• Postman installed
• Valid tenant ID for a CareConnect tenant that supports Provider Directory APIs in the Preview environment
• Basic understanding of FHIR concepts

Getting Started

To begin testing, you'll need a Provider Directory base URL for a CareConnect payer tenant. You can discover available Provider Directory APIs using the Service Base URL endpoint, or contact Netsmart to obtain access to a Preview tenant with provider directory data.

Overview

The FHIR Provider Directory APIs provide access to payer network information without requiring authentication. This tutorial covers:

1. Setting up a Postman environment with variables
2. Creating a collection for provider directory requests
3. Making four key API requests:
   • CapabilityStatement (Public)
   • Organization Read (Public)
   • Organization Search GET (Public)
   • Organization Search POST (Public)
4. Troubleshooting common issues

Step 1: Create a Postman Environment

Environments in Postman store variables that can be reused across requests, making it easy to switch between different FHIR servers or configurations.

Creating the Environment

1. Open Postman
2. Click the Environments tab in the left sidebar
3. Click Create Environment
4. Name your environment (e.g., "FHIR Provider Directory - Dev")

Adding Environment Variables

Add the following variables to your environment:

Preview

Variable Name	Type	Initial Value	Current Value
tenant_id	default	your-tenant-id	your-tenant-id
base_url	default	https://fhirtest.netsmartcloud.com/payer/provider-directory/v2	https://fhirtest.netsmartcloud.com/payer/provider-directory/v2

Production

Variable Name	Type	Initial Value	Current Value
tenant_id	default	your-tenant-id	your-tenant-id
base_url	default	https://fhir.netsmartcloud.com/payer/provider-directory/v2	https://fhir.netsmartcloud.com/payer/provider-directory/v2

Replace your-tenant-id with your actual CareConnect tenant ID.

Save and Select Environment

1. Select Save
2. Select your environment from the dropdown in the top-right corner

Environment Reuse

If you're working with multiple CareConnect API tutorials, consider creating a shared environment with standardized variable names. This allows you to reuse the same environment across different API collections. See our Shared Environment Setup Guide for standardized variable naming conventions.

Step 2: Create a Collection

Creating the Collection

1. Select Collections in the left sidebar
2. Select Create Collection
3. Name it "FHIR Provider Directory"
4. Add a description: "Collection for testing FHIR Provider Directory APIs"

Adding Collection Variables

Add variables for temporary data generated during the testing workflow:

1. In your collection, select the Variables tab
2. Add the following variables:

Variable Name	Initial Value	Current Value
organization_id

3. Select Save

Setting Authorization

1. In your collection, select the Authorization tab
2. Set Type to No Auth
3. Select Save

Note: Provider Directory APIs are publicly accessible and do not require authentication.

Step 3: Create API Requests

Request 1: CapabilityStatement

The CapabilityStatement describes the FHIR server's capabilities for the Provider Directory.

1. In your collection, select Add request
2. Name: "Get CapabilityStatement"
3. Method: GET
4. URL: {{base_url}}/:tenant_id/metadata
5. Authorization tab: Set Type to Inherit auth from parent
6. Params tab:
   • Path Variables: Set tenant_id to your tenant ID or {{tenant_id}} to use environment variable
7. Select Save

Test the request:

• Select Send
• You should receive a CapabilityStatement resource in JSON format
• Look for supported resources like Organization, Practitioner, Location, and HealthcareService
• See the Provider Directory API documentation for complete resource details

Request 2: Organization Search (GET)

Start with an organization search to find available organizations and automatically set an organization ID for subsequent requests.

1. Add a new request: "Organization Search (GET)"
2. Method: GET
3. URL: {{base_url}}/:tenant_id/Organization
4. Authorization tab: Set Type to Inherit auth from parent
5. Params tab:
   • Path Variables: Set tenant_id to your tenant ID or {{tenant_id}} to use environment variable
   • Query Params: Add query parameters:
     • Key: _count, Value: 5
6. Select Save

Test the request:

• Select Send
• In the response, look for the entry array
• Each organization will have an id field under entry[].resource.id
• Copy an organization ID from the response (e.g., "org-12345")
• Go to your collection's Variables tab and update the organization_id variable with this value

Request 3: Organization Read

Now read the specific organization using the ID extracted from the search.

1. Add a new request: "Organization Read"
2. Method: GET
3. URL: {{base_url}}/:tenant_id/Organization/:organization_id
4. Authorization tab: Set Type to Inherit auth from parent
5. Params tab:
   • Path Variables:
     • Set tenant_id to your tenant ID or {{tenant_id}} to use environment variable
     • Set organization_id to a specific Organization ID or {{organization_id}} to use environment variable
6. Select Save

Organization ID Required

This request requires a valid organization ID. Run the Organization Search request first, then copy an organization ID from the search results and update your organization_id environment variable.

Test the request:

• Ensure organization_id collection variable is set
• Select Send
• You should receive a single Organization resource in JSON format

Request 4: Organization Search (GET) with Parameters

Search for organizations using specific query parameters.

1. Add a new request: "Organization Search (GET) with Parameters"
2. Method: GET
3. URL: {{base_url}}/:tenant_id/Organization
4. Authorization tab: Set Type to Inherit auth from parent
5. Params tab: Add query parameters:
   • Key: name, Value: Hospital
   • Key: type, Value: prov
   • Key: _count, Value: 10
6. Select Save

Test the request:

• Select Send
• You should receive organizations matching the search criteria
• Try different search parameters to see how results change
• See the Organization resource documentation for supported search parameters

Request 5: Organization Search (POST)

Search for organizations using a POST request with form data.

1. Add a new request: "Organization Search (POST)"
2. Method: POST
3. URL: {{base_url}}/:tenant_id/Organization/_search
4. Authorization tab: Set Type to Inherit auth from parent
5. Body tab: Select x-www-form-urlencoded and add:
   • Key: name, Value: Hospital
   • Key: type, Value: prov
   • Key: _count, Value: 10
6. Select Save

Test the request:

• Select Send
• Compare results with the GET search to verify they return the same data
• Note that search parameters are in the request body, not the URL

Note: Postman automatically sets the Content-Type header to application/x-www-form-urlencoded when you select this body type.

Step 4: Testing Your Requests

Recommended Testing Order

1. Test CapabilityStatement - Verify server connectivity and supported resources
2. Test Organization Search (GET) - Find available organizations
3. Update organization_id variable - Copy an organization ID from search results
4. Test Organization Read - Verify organization-specific access
5. Test remaining search requests - Try different search methods and parameters

Validating Responses

For each request, verify:

• Status code is 200 OK
• Response contains valid FHIR JSON
• Required fields are present
• Data matches expected format

Troubleshooting Common Issues

Request Issues

For detailed error responses and comprehensive troubleshooting guidance, see the Common Errors page in the Provider Directory API documentation.

Problem: 404 Not Found on requests

• Solution: Verify your base_url environment variable is correct
• Ensure your path variables for tenant_id are properly set
• Check that the tenant supports Provider Directory APIs

Problem: "HAPI-0333: Access denied by rule: Request is not authorized for this Tenant" error

• Solution: This error can occur due to tenant configuration OR insufficient authorization:
  • Tenant Issues: Verify your tenant_id path variable is set correctly in each request
  • Tenant Issues: Ensure the tenant ID matches your CareConnect configuration
  • Tenant Issues: Check that the tenant supports Provider Directory APIs
  • Authorization Issues: Verify your access has the required permissions for the resource or operation
  • Authorization Issues: Confirm the tenant configuration includes access to the specific FHIR resources and operations

Problem: Empty search results

• Solution: Try broader search criteria
• Check if provider directory data exists for the endpoint
• Verify search parameter names match FHIR specification
• Consult the Provider Directory API documentation for supported parameters

Problem: 403 Forbidden errors

• Solution: Verify the endpoint supports Provider Directory APIs
• Check if the specific resource type is supported
• Contact Netsmart to confirm endpoint configuration

Problem: 400 Bad Request errors

• Solution: Check the Common Errors page in the Provider Directory API documentation for detailed examples
• Verify search parameter syntax and values
• Ensure request format matches API expectations

Network Issues

Problem: SSL/TLS certificate errors

• Solution: In Postman Settings, turn off "SSL certificate verification" for testing
• Warning: Only disable when testing with the Preview environment

Problem: CORS errors in browser

• Solution: Use Postman desktop app instead of web version
• CORS doesn't apply to Postman desktop requests

Environment Issues

Problem: Variables not resolving (showing {{variable_name}})

• Solution: Ensure environment is selected in top-right dropdown
• Check variable names match exactly (case-sensitive)
• Verify variables have values set

Best Practices

Organization

• Group related requests in folders within collections
• Use descriptive names for requests and variables
• Add documentation to requests explaining their purpose
• Include example responses for reference

Testing

• Add tests to requests to validate responses automatically
• Use pre-request scripts to set up dynamic data
• Create test suites that can run multiple requests in sequence
• Request different formats: Use the Accept header to request XML instead of JSON:
  • For JSON (default): Accept: application/fhir+json
  • For XML: Accept: application/fhir+xml
  • Add these in the Headers tab of your requests

Security

• Use HTTPS connections (TLS) for all requests
• Create separate environments for different endpoints:
  • CareConnect Provider Directory - Endpoint A
  • CareConnect Provider Directory - Endpoint B
• Each endpoint may have different provider directory data and configurations

Next Steps

Once you've mastered basic Organization access, consider exploring:

• Additional Provider Directory Resources: Create requests for other directory resources:
  • {{base_url}}/:tenant_id/Practitioner (individual practitioners)
  • {{base_url}}/:tenant_id/PractitionerRole (practitioner roles and affiliations)
  • {{base_url}}/:tenant_id/Location (service locations)
  • {{base_url}}/:tenant_id/HealthcareService (available services)
  • {{base_url}}/:tenant_id/InsurancePlan (insurance plan information)
• Advanced Search Parameters: Explore geographic searches, specialty filters, and network-specific queries

See the Provider Directory API documentation for complete details on all supported resources and operations.

Additional Resources

• CareConnect Provider Directory API
• Service Base URLs documentation
• FHIR R4 Specification
• Da Vinci PDEX Plan Net Implementation Guide
• Postman Documentation
• FHIR Organization Resource