Skip to main content

CapabilityStatement

Overview​

The CapabilityStatement resource documents the capabilities, behaviors, and supported operations of a FHIR server for the Provider Directory API. It serves as a machine-readable description of what the server can do and how clients should interact with it.

Key Use Cases:

  • Discover supported resources and operations
  • Verify server capabilities before making requests
  • Understand search parameters and interaction patterns
  • Validate API compatibility for client applications

Relationships to Other Resources:

  • All Resources - Describes capabilities for all Provider Directory resources
  • Operations - Documents supported CRUD and search operations
  • Search Parameters - Lists available search criteria for each resource

Resource Schema​

Key fields in the CapabilityStatement resource:

{
  "resourceType": "CapabilityStatement",
  "id": "cc-fhir-pdex-directory-server",
  "name": "NTST_CARECONNECT_FHIR_PDEX_PROVIDER_DIRECTORY",
  "title": "Netsmart CareConnect FHIR PDex Provider Directory Capability Statement",
  "status": "active",
  "date": "2025-01-15T19:27:47.746+00:00",
  "publisher": "Netsmart Technologies, Inc.",
  "kind": "instance",
  "software": {
    "name": "Netsmart CareConnect FHIR Connector",
    "version": "1.0.19"
  },
  "implementation": {
    "description": "HAPI FHIR",
    "url": "https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}"
  },
  "fhirVersion": "4.0.1",
  "format": [
    "application/fhir+xml",
    "xml",
    "application/fhir+json",
    "json",
    "application/x-turtle",
    "ttl"
  ],
  "rest": [
    {
      "mode": "server",
      "resource": [
        {
          "type": "Organization",
          "profile": "http://hl7.org/fhir/StructureDefinition/Organization",
          "supportedProfile": [
            "http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Organization",
            "http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Network"
          ],
          "interaction": [
            {
              "code": "search-type"
            },
            {
              "code": "read"
            }
          ],
          "searchParam": [
            {
              "name": "address",
              "type": "string",
              "documentation": "A server defined search that may match any of the string fields in the Address"
            },
            {
              "name": "address-city",
              "type": "string",
              "documentation": "A city specified in an address"
            },
            {
              "name": "address-postalcode",
              "type": "string",
              "documentation": "A postal code specified in an address"
            },
            {
              "name": "address-state",
              "type": "string",
              "documentation": "A state specified in an address"
            },
            {
              "name": "identifier",
              "type": "token",
              "documentation": "Any identifier for the organization"
            },
            {
              "name": "name",
              "type": "string",
              "documentation": "A portion of the organization's name or alias"
            }
          ]
        },
        {
          "type": "Practitioner",
          "profile": "http://hl7.org/fhir/StructureDefinition/Practitioner",
          "supportedProfile": [
            "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner"
          ],
          "interaction": [
            {
              "code": "search-type"
            },
            {
              "code": "read"
            }
          ],
          "searchParam": [
            {
              "name": "family",
              "type": "string",
              "documentation": "A portion of the family name"
            },
            {
              "name": "given",
              "type": "string",
              "documentation": "A portion of the given name"
            },
            {
              "name": "identifier",
              "type": "token",
              "documentation": "A practitioner's Identifier"
            },
            {
              "name": "name",
              "type": "string",
              "documentation": "A server defined search that may match any of the string fields in the HumanName"
            }
          ]
        },
        {
          "type": "Location",
          "profile": "http://hl7.org/fhir/StructureDefinition/Location",
          "supportedProfile": [
            "http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Location",
            "http://hl7.org/fhir/us/core/StructureDefinition/us-core-location"
          ],
          "interaction": [
            {
              "code": "search-type"
            },
            {
              "code": "read"
            }
          ],
          "searchParam": [
            {
              "name": "address",
              "type": "string",
              "documentation": "A (part of the) address of the location"
            },
            {
              "name": "address-city",
              "type": "string",
              "documentation": "A city specified in an address"
            },
            {
              "name": "address-postalcode",
              "type": "string",
              "documentation": "A postal code specified in an address"
            },
            {
              "name": "address-state",
              "type": "string",
              "documentation": "A state specified in an address"
            },
            {
              "name": "organization",
              "type": "reference",
              "documentation": "Searches for locations that are managed by the provided organization"
            },
            {
              "name": "type",
              "type": "token",
              "documentation": "A code for the type of location"
            }
          ]
        }
      ]
    }
  ]
}

Key Fields:

  • fhirVersion - FHIR specification version supported (4.0.1)
  • format - Supported content types (JSON, XML, Turtle)
  • rest.resource - Supported resources and their operations (10 resources)
  • searchParam - Available search parameters for each resource
  • interaction - Supported operations (read, search-type)
  • supportedProfile - FHIR profiles implemented for each resource

Operations​

Read​

The CapabilityStatement supports only the read operation and is publicly accessible without authentication.

GET /metadata
Example Request
curl -X GET https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/metadata \
    -H "Accept: application/fhir+json"

Examples​

Request Examples​

Get server capabilities (JSON)
curl -X GET https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/metadata \
    -H "Accept: application/fhir+json"
Get server capabilities (XML)
curl -X GET https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/metadata \
    -H "Accept: application/fhir+xml"

Response Examples​

Successful CapabilityStatement Response​

Provider Directory CapabilityStatement (Abbreviated)
{
  "resourceType": "CapabilityStatement",
  "id": "cc-fhir-pdex-directory-server",
  "name": "NTST_CARECONNECT_FHIR_PDEX_PROVIDER_DIRECTORY",
  "title": "Netsmart CareConnect FHIR PDex Provider Directory Capability Statement",
  "status": "active",
  "date": "2025-01-15T19:27:47.746+00:00",
  "publisher": "Netsmart Technologies, Inc.",
  "kind": "instance",
  "software": {
    "name": "Netsmart CareConnect FHIR Connector",
    "version": "1.0.19"
  },
  "implementation": {
    "description": "HAPI FHIR",
    "url": "https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}"
  },
  "fhirVersion": "4.0.1",
  "format": [
    "application/fhir+xml",
    "xml",
    "application/fhir+json",
    "json",
    "application/x-turtle",
    "ttl"
  ],
  "rest": [
    {
      "mode": "server",
      "resource": [
        {
          "type": "Organization",
          "profile": "http://hl7.org/fhir/StructureDefinition/Organization",
          "supportedProfile": [
            "http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Organization",
            "http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Network",
            "http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization"
          ],
          "interaction": [
            {
              "code": "search-type"
            },
            {
              "code": "read"
            }
          ],
          "searchParam": [
            {
              "name": "address",
              "type": "string",
              "documentation": "A server defined search that may match any of the string fields in the Address"
            },
            {
              "name": "address-city",
              "type": "string",
              "documentation": "A city specified in an address"
            },
            {
              "name": "address-postalcode",
              "type": "string",
              "documentation": "A postal code specified in an address"
            },
            {
              "name": "address-state",
              "type": "string",
              "documentation": "A state specified in an address"
            },
            {
              "name": "identifier",
              "type": "token",
              "documentation": "Any identifier for the organization"
            },
            {
              "name": "name",
              "type": "string",
              "documentation": "A portion of the organization's name or alias"
            }
          ]
        }
      ]
    }
  ]
}

Note: This is an abbreviated example showing key structure. The actual CapabilityStatement includes all 10 supported resources (Endpoint, HealthcareService, InsurancePlan, Location, OperationDefinition, Organization, OrganizationAffiliation, Practitioner, PractitionerRole) with their complete search parameters, profiles, and include/revinclude capabilities.

Integration Patterns​

Common Workflows​

1. Server Discovery and Validation

# Step 1: Get server capabilities
GET /metadata

# Step 2: Validate supported resources
# Check rest.resource array for required resources

# Step 3: Verify search parameters
# Check searchParam arrays for needed search criteria

# Step 4: Confirm supported formats
# Check format array for JSON/XML support

2. Dynamic Client Configuration

# Step 1: Retrieve capability statement
GET /metadata

# Step 2: Parse supported operations
# Configure client based on available interactions

# Step 3: Build search queries
# Use documented search parameters

# Step 4: Handle unsupported features gracefully
# Check capabilities before attempting operations
  • All Provider Directory Resources - CapabilityStatement describes capabilities for all resources
  • Search Parameters - Documents available search criteria
  • Profiles - References supported FHIR profiles

Usage Patterns​

Check Resource Support:

// Example: Check if Organization search is supported
const capability = await fetch('/metadata').then(r => r.json());
const orgResource = capability.rest[0].resource.find(r => r.type === 'Organization');
const supportsSearch = orgResource.interaction.some(i => i.code === 'search-type');

Validate Search Parameters:

// Example: Check available Organization search parameters
const orgSearchParams = orgResource.searchParam.map(p => p.name);
// ['name', 'address-city', 'address-state', 'type']

Error Handling​

The CapabilityStatement resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.

CapabilityStatement-Specific Error Scenarios​

  • 404 Not Found: Tenant doesn't exist or doesn't support Provider Directory APIs
  • 500 Internal Server Error: Server error retrieving capability statement
  • 403 Forbidden: Access denied to the metadata endpoint

Troubleshooting Tips​

  • Tenant Validation: Ensure the tenant ID supports Provider Directory APIs
  • Format Support: Check the format array for supported content types
  • Resource Availability: Verify required resources are listed in the rest.resource array
  • Search Parameters: Confirm needed search parameters are documented before using them

Supported Profiles​