Skip to main content

CapabilityStatement

Overview​

The CapabilityStatement resource documents the capabilities, behaviors, and supported operations of a FHIR server for the Provider System Access 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 System Access 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-provider-system-access-server",
  "name": "NTST_CARECONNECT_FHIR_PROVIDER_SYSTEM_ACCESS",
  "title": "Netsmart CareConnect FHIR Provider System Access 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/provider/system-access/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/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"
            }
          ]
        },
        {
          "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/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
  • searchParam - Available search parameters for each resource
  • interaction - Supported CRUD operations (create, read, update, search-type)
  • operation - Extended operations like $docref, $export
  • supportedProfile - FHIR profiles implemented for each resource

Understanding Interactions and Operations​

Interaction Codes​

The interaction array for each resource indicates which CRUD operations are supported:

  • read - Retrieve a specific resource by ID using GET /ResourceType/{id}
  • create - Create a new resource using POST /ResourceType
  • update - Update an existing resource using PUT /ResourceType/{id}
  • search-type - Search for resources using GET /ResourceType?params or POST /ResourceType/_search

Example from CapabilityStatement:

{
  "type": "DocumentReference",
  "interaction": [
    { "code": "create" },
    { "code": "read" },
    { "code": "update" },
    { "code": "search-type" }
  ]
}

Extended Operations​

The operation array lists custom operations beyond standard CRUD:

  • $docref - US Core document fetch operation for DocumentReference
  • $export - Bulk data export operation for Group resources

Example from CapabilityStatement:

{
  "type": "DocumentReference",
  "operation": [
    {
      "name": "docref",
      "definition": "http://hl7.org/fhir/us/core/OperationDefinition/docref|6.1.0"
    }
  ]
}
{
  "type": "Group",
  "operation": [
    {
      "name": "export",
      "definition": "http://hl7.org/fhir/uv/bulkdata/OperationDefinition/group-export|2.0.0"
    }
  ]
}

Search Parameters​

Each resource's searchParam array documents available query parameters:

{
  "name": "patient",
  "type": "reference",
  "documentation": "The subject of the report if a patient"
}

Use these parameters in search requests: GET /DiagnosticReport?patient=Patient/123

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/provider/system-access/v2/{tenant-id}/metadata \
    -H "Accept: application/fhir+json"

Examples​

Request Examples​

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

Response Examples​

Successful CapabilityStatement Response​

Provider System Access CapabilityStatement (Abbreviated)
{
  "resourceType": "CapabilityStatement",
  "id": "cc-fhir-provider-system-access-server",
  "name": "NTST_CARECONNECT_FHIR_PROVIDER_SYSTEM_ACCESS",
  "title": "Netsmart CareConnect FHIR Provider System Access 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/provider/system-access/v2/{tenant-id}"
  }
}

Integration Patterns​

Discovery Workflow​

  1. Retrieve CapabilityStatement - Start by fetching the server's capabilities
  2. Parse Resource Capabilities - For each resource you need:
    • Check interaction array for supported CRUD operations
    • Review operation array for extended operations like $docref or $export
    • Examine searchParam array for available query parameters
  3. Validate Profiles - Verify supportedProfile matches your implementation requirements
  4. Check Formats - Confirm format array includes your preferred content type
  5. Build Client Logic - Implement only operations listed in the CapabilityStatement

Best Practices​

  • Always check CapabilityStatement before attempting operations
  • Don't assume standard operations - verify each interaction is listed
  • Follow operation definitions - use the linked OperationDefinition URLs for parameter details
  • Respect search parameter types - use correct syntax for string, token, reference, etc.
  • Cache CapabilityStatement - it changes infrequently, reduce unnecessary requests

Common Use Cases​

  • Resource Discovery - Determine what resources are available before building queries
  • Search Parameter Validation - Verify search parameters before implementing search logic
  • Profile Compliance - Check which FHIR profiles are supported for validation
  • Format Negotiation - Understand supported content types for requests

Error Handling​

For common errors and troubleshooting guidance, see Common Errors.

Supported Profiles​