Testing FHIR User Access Brands with Postman

This tutorial demonstrates how to retrieve tenant-specific User Access Brands using Postman. These brands are published following the User-access Brands and Endpoints specification from SMART App Launch v2.2.0.

Prerequisites

• Postman installed
• Valid tenant ID for a CareConnect tenant
• No authentication required - this is a publicly accessible endpoint

Related Tutorials

This tutorial is part of a series for testing CareConnect FHIR APIs:

• Discovery APIs (No Authentication Required):

  • Service Base URLs - Discover all available FHIR endpoints
  • User Access Brands (this tutorial) - Get tenant-specific brands and endpoints
  • Provider Directory - Search provider network information

• Authenticated APIs (OAuth 2.0 Required):

  • Patient Access - Patient-authorized access to health data
  • Practitioner Access - Provider access to patient data
  • System Access - System-level access for backend applications

Recommended Flow: Start with Service Base URLs or User Access Brands to discover endpoints, then use the appropriate authenticated API tutorial based on your application type.

Tenant-Specific Endpoint

Unlike the Service Base URLs endpoint, User Access Brands requires a specific tenant ID in the URL path. Each tenant has its own brands bundle that may contain different organizations and endpoints.

Step 1: Create a Postman Environment

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

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 User Access Brands - Preview")

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/brand	https://fhirtest.netsmartcloud.com/brand

Production

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

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 User Access Brands"
4. Add a description: "Collection for testing FHIR User Access Brands APIs"

Setting Authorization

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

Note: User Access Brands APIs are publicly accessible and do not require authentication.

Step 3: Create API Request

Request: Get User Access Brands

1. In your collection, select Add request
2. Name: "Get User Access Brands"
3. Method: GET
4. URL: {{base_url}}/:tenant_id/brands.json
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

Step 4: Set Headers

1. In the Headers tab, add the following header:
   • Key: Accept
   • Value: application/fhir+json

Step 5: Test the Request

Test the request:

• In the Params tab under Path Variables, set tenant_id to either:
  • A specific tenant ID (e.g., tenant-123)
  • {{tenant_id}} to use your environment variable
• Select Send
• You should receive a 200 OK response with a FHIR Bundle

Expected Response

You should receive a 200 OK response with an HL7 FHIR R4 Bundle containing:

• Primary Brand Organization - The main healthcare organization for this tenant
• Secondary Brand Organizations - Additional organizations (optional)
• Service Base URL Endpoints - FHIR API endpoints specific to this tenant
• fullUrl References - URN-based identifiers for bundle entries

Sample Response Structure

{
  "resourceType": "Bundle",
  "id": "brands.json",
  "meta": {
    "lastUpdated": "2025-01-15T15:00:53.636620392Z"
  },
  "type": "collection",
  "timestamp": "2025-01-15T15:00:53.636620392Z",
  "entry": [
    {
      "fullUrl": "urn:uuid:example-tenant-org-123",
      "resource": {
        "resourceType": "Organization",
        "id": "example-tenant-org-123",
        "meta": {
          "lastUpdated": "2024-12-23T22:49:32.277634175Z"
        },
        "identifier": [
          {
            "system": "urn:oid:2.16.840.1.113883.3.3569",
            "value": "2.16.840.1.113883.3.3569.example123"
          }
        ],
        "active": true,
        "name": "Example Tenant Healthcare Organization",
        "telecom": [
          {
            "system": "url",
            "value": "https://www.example-tenant.org/"
          }
        ],
        "endpoint": [
          {
            "reference": "Endpoint/example-tenant-endpoint-456"
          }
        ]
      }
    },
    {
      "fullUrl": "urn:uuid:example-tenant-endpoint-456",
      "resource": {
        "resourceType": "Endpoint",
        "id": "example-tenant-endpoint-456",
        "meta": {
          "lastUpdated": "2024-12-23T22:49:26.693903971Z"
        },
        "extension": [
          {
            "url": "http://hl7.org/fhir/StructureDefinition/endpoint-fhir-version",
            "valueCode": "4.0.1"
          }
        ],
        "status": "active",
        "connectionType": {
          "system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
          "code": "hl7-fhir-rest"
        },
        "name": "Netsmart CareConnect Certified Provider Patient Access FHIR v2",
        "contact": [
          {
            "system": "url",
            "value": "https://www.example-tenant.org"
          }
        ],
        "payloadType": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/endpoint-payload-type",
                "code": "none"
              }
            ]
          }
        ],
        "address": "https://fhir.netsmartcloud.com/provider/patient-access/v2/example-tenant-123"
      }
    }
  ]
}

Troubleshooting

404 Not Found:

• Verify the tenant ID is correct and exists
• Check the URL format matches the expected pattern
• Ensure the tenant supports User Access Brands

Request fails or times out:

• Verify the URL is correct for your target environment
• Check your internet connection
• Ensure Postman can access external URLs

Unexpected response format:

• Confirm the Accept header is set to application/fhir+json
• Verify you're using the correct endpoint URL with tenant ID

Empty bundle or no entries:

• The tenant may not have any configured brands
• Contact Netsmart to verify tenant configuration
• Try a different tenant ID if available

Comparing with Service Base URLs

The key differences between User Access Brands and Service Base URLs:

Aspect	Service Base URLs	User Access Brands
URL Pattern	/brand/brands.json	/brand/{tenant-id}/brands.json
Scope	All available brands	Tenant-specific brands
Tenant ID	Not required	Required in URL path
Use Case	Discover all endpoints	Get specific tenant brands

Best Practices for Multi-Tutorial Development

Collection Organization

When working with multiple CareConnect API tutorials:

Option 1: Separate Collections

• Use consistent naming: CareConnect - [API Type] (e.g., "CareConnect - User Access Brands")
• Share environments: Use the same environment across related collections
• Authorization at collection level: Each collection has its own OAuth configuration

Option 2: Shared Multi-API Collection

• Single collection: CareConnect Multi-API Collection
• Organize by folders: Group requests by API type within folders
• Authorization at folder level: Configure OAuth per folder, not collection
  • Discovery APIs folder: No Auth
  • Patient Access folder: OAuth with patient scopes
  • System Access folder: OAuth Client Credentials with system scopes
• Standardize variable names: Use consistent names like tenant_id, domain, patient_id across all folders

Environment Reuse Strategy

• Single Multi-API Environment: Create one environment with all base URLs and scope variables for different API types
• API-Specific Environments: Separate environments per API type with consistent variable naming
• Tenant-Specific Environments: One environment per tenant if working with multiple tenants

Key Variables for Shared Collections:

• patient_scope, practitioner_scope, system_scope - Different OAuth scopes per API type
• patient_access_base_url, system_access_base_url - Different base URLs per API type
• client_id, client_secret - May differ per API registration

Next Steps

• Extract tenant-specific endpoints from the Endpoint.address field
• Test discovered endpoints by calling their /metadata endpoint
• Compare results with the global Service Base URLs to understand tenant-specific differences
• Set up shared environment using our Shared Environment Setup Guide
• Review the User Access Brands documentation for additional details
• Explore other Postman tutorials for FHIR API testing

Related Resources

• User Access Brands API Documentation
• Service Base URLs API Documentation
• Service Base URLs Postman Tutorial
• SMART App Launch Implementation Guide
• User-access Brands and Endpoints Specification