Endpoint

Overview

The Endpoint resource provides technical details for electronic services and endpoints that can be used to access healthcare services. It defines connection information, protocols, and access methods for digital health services within provider networks.

Key Use Cases:

• Discover technical endpoints for healthcare services
• Find API endpoints for provider systems
• Locate web portals and electronic service access points
• Verify endpoint connectivity and protocols

Relationships to Other Resources:

• Organization - Organizations that manage or operate endpoints
• HealthcareService - Services accessible through endpoints
• PractitionerRole - Practitioner services available via endpoints
• Location - Physical locations associated with endpoints

Resource Schema

Key fields in the Endpoint resource:

{
  "resourceType": "Endpoint",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/endpoint-id",
      "value": "EP-123"
    }
  ],
  "status": "active|suspended|error|off|entered-in-error|test",
  "connectionType": {
    "system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
    "code": "hl7-fhir-rest",
    "display": "HL7 FHIR REST"
  },
  "name": "Provider Portal API",
  "managingOrganization": {
    "reference": "Organization/org-123",
    "display": "Sacramento Medical Center"
  },
  "contact": [
    {
      "system": "email",
      "value": "api-support@sacmedcenter.org",
      "use": "work"
    }
  ],
  "period": {
    "start": "2024-01-01"
  },
  "payloadType": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/endpoint-payload-type",
          "code": "application/fhir+json",
          "display": "FHIR JSON"
        }
      ]
    }
  ],
  "payloadMimeType": [
    "application/fhir+json",
    "application/fhir+xml"
  ],
  "address": "https://api.sacmedcenter.org/fhir/R4",
  "header": [
    "Authorization: Bearer {token}",
    "Accept: application/fhir+json"
  ]
}

Key Fields:

• connectionType - Type of endpoint (FHIR REST, web portal, etc.)
• address - URL or connection address for the endpoint
• managingOrganization - Organization responsible for the endpoint
• payloadType - Types of data/content supported
• status - Current operational status of the endpoint
• contact - Technical contact information

Operations

Read

Retrieve a specific endpoint by ID.

Production

GET /Endpoint/{id}

Example Request

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

Preview

GET /Endpoint/{id}

Example Request

curl -X GET https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Endpoint/ep-123 \
    -H "Accept: application/fhir+json"

Search

Search for endpoints using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production

GET /Endpoint?parameter=value

Preview

GET /Endpoint?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production

POST /Endpoint/_search

Preview

POST /Endpoint/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
connection-type	token	No	Type of connection	connection-type=hl7-fhir-rest
name	string	No	Endpoint name (partial match)	name=Portal
organization	reference	No	Managing organization	organization=Organization/org-123
payload-type	token	No	Supported payload type	payload-type=application/fhir+json
status	token	No	Endpoint status	status=active

Common Search Patterns

Find active endpoints:

GET /Endpoint?status=active&_count=10

Search by organization:

GET /Endpoint?organization=Organization/org-123

Find FHIR endpoints:

GET /Endpoint?connection-type=hl7-fhir-rest

Search by payload type:

GET /Endpoint?payload-type=application/fhir+json

Examples

Request Examples

Production

Find FHIR REST endpoints

curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Endpoint/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "connection-type=hl7-fhir-rest&status=active"

Search endpoints by organization

curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Endpoint/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "organization=Organization/org-123&_include=Endpoint:organization"

Find web portal endpoints

curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Endpoint/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "connection-type=secure-web&name=Portal"

Preview

Find FHIR REST endpoints

curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Endpoint/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "connection-type=hl7-fhir-rest&status=active"

Search endpoints by organization

curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Endpoint/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "organization=Organization/org-123&_include=Endpoint:organization"

Find web portal endpoints

curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Endpoint/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "connection-type=secure-web&name=Portal"

Response Examples

Successful Search Response

Endpoint Search Bundle

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Endpoint",
        "id": "ep-123",
        "status": "active",
        "connectionType": {
          "system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
          "code": "hl7-fhir-rest",
          "display": "HL7 FHIR REST"
        },
        "name": "Provider FHIR API",
        "managingOrganization": {
          "reference": "Organization/org-456",
          "display": "Sacramento Health System"
        },
        "contact": [
          {
            "system": "email",
            "value": "fhir-support@sachealthsystem.org",
            "use": "work"
          }
        ],
        "payloadType": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/endpoint-payload-type",
                "code": "application/fhir+json",
                "display": "FHIR JSON"
              }
            ]
          }
        ],
        "payloadMimeType": [
          "application/fhir+json",
          "application/fhir+xml"
        ],
        "address": "https://fhir.sachealthsystem.org/R4"
      }
    }
  ]
}

Integration Patterns

Common Workflows

1. Discover Organization APIs

# Step 1: Find organization
GET /Organization?name=Health System&type=prov

# Step 2: Get all endpoints for organization
GET /Endpoint?organization=Organization/org-123

# Step 3: Filter by connection type
GET /Endpoint?organization=Organization/org-123&connection-type=hl7-fhir-rest

2. Find Service Endpoints

# Step 1: Find healthcare service
GET /HealthcareService?name=Patient Portal

# Step 2: Get associated endpoints
GET /Endpoint?service=HealthcareService/svc-456

# Step 3: Verify endpoint status
GET /Endpoint/ep-789

Related Resources

• Organization - Organizations managing endpoints
• HealthcareService - Services accessible via endpoints
• PractitionerRole - Practitioner services with endpoints
• Location - Physical locations with digital endpoints

Include Parameters

Use _include to fetch related resources:

# Get endpoints with managing organization details
GET /Endpoint?status=active&_include=Endpoint:organization

# Get endpoints with associated services
GET /Endpoint?connection-type=hl7-fhir-rest&_include=Endpoint:service

Error Handling

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

Endpoint-Specific Error Scenarios

• 404 Not Found: Endpoint ID doesn't exist or endpoint is inactive
• 400 Bad Request: Invalid connection type codes or malformed parameters
• Empty Results: No endpoints match the search criteria

Troubleshooting Tips

• No Active Endpoints: Check endpoint status and verify organizations have published endpoints
• Connection Type Issues: Use standard endpoint connection type codes from HL7 terminology
• Organization References: Ensure managing organization references are valid

Supported Profiles

• HL7 FHIR R4 Endpoint
• DaVinci PDex Plan-Net Endpoint