FHIR API Overview

The Nestmed platform provides a FHIR R4 API designed for seamless integration with Electronic Health Records (EHRs) and other healthcare systems. This API transforms our internal data into standardized FHIR resources, providing read access to clinical information.

This FHIR API is currently in alpha. Features and endpoints may change.

Base URL

https://{tenant_id}.api.nestmed.com/fhir/r4/v1

Authentication

The FHIR API uses OAuth 2.0 for authentication, supporting both:

Client Credentials
Authorization Code

For system-to-system integration:

POST /auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=patient/*.read

For user-facing applications:

# Step 1: Redirect to authorization
GET /auth/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=patient/*.read&
  state=RANDOM_STATE

# Step 2: Exchange code for token
POST /auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Supported Resources

Our FHIR API provides comprehensive resources specifically tailored for home health requirements, including OASIS assessments, Medicare compliance, and PDGM groupings:

Core Clinical Resources

Patient

Resource: Patient Endpoint: /v1/Patient/{id} Source: Internal patient recordsMaps patient demographics, identifiers, and contact information with home health specific extensions.

{
  "resourceType": "Patient",
  "id": "pat_123456789",
  "identifier": [{
    "system": "https://nestmed.com/mrn",
    "value": "MRN-12345"
  }],
  "name": [{
    "family": "Doe",
    "given": ["John"]
  }],
  "birthDate": "1945-03-15",
  "extension": [{
    "url": "http://nestmed.com/fhir/extensions/medicare-beneficiary-id",
    "valueString": "1EG4-TE5-MK73"
  }]
}

EpisodeOfCare

Resource: EpisodeOfCare Endpoint: /v1/EpisodeOfCare Source: Internal episodesRepresents periods of care delivery.

{
  "resourceType": "EpisodeOfCare",
  "id": "ep_987654321",
  "status": "active",
  "patient": {
    "reference": "Patient/pat_123456789"
  },
  "period": {
    "start": "2024-11-01"
  }
}

Encounter

Resource: Encounter Endpoint: /v1/Encounter Source: Internal visitsIndividual visit encounters.

{
  "resourceType": "Encounter",
  "id": "visit_789012345",
  "status": "finished",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "HH",
    "display": "home health"
  },
  "subject": {
    "reference": "Patient/pat_123456789"
  },
  "participant": [{
    "individual": {
      "reference": "Practitioner/clin_987654321"
    }
  }]
}

Home Health Specific Resources

ServiceRequest

Resource: ServiceRequest Endpoint: /v1/ServiceRequest Source: Physician orders/485 Plan of CareCritical for home health orders and Plan of Care documentation.

{
  "resourceType": "ServiceRequest",
  "id": "order_485_12345",
  "status": "active",
  "intent": "order",
  "code": {
    "coding": [{
      "system": "http://snomed.info/sct",
      "code": "385763009",
      "display": "Home health skilled nursing"
    }]
  },
  "orderDetail": [{
    "text": "SN 3x/week x 9 weeks for wound care"
  }],
  "authoredOn": "2024-01-01",
  "occurrencePeriod": {
    "start": "2024-01-01",
    "end": "2024-02-29"
  },
  "extension": [{
    "url": "http://nestmed.com/fhir/extensions/certification-period",
    "valuePeriod": {
      "start": "2024-01-01",
      "end": "2024-02-29"
    }
  }]
}

Observation

Resource: Observation Endpoint: /v1/Observation Source: Vitals, assessments, OASIS itemsEssential for OASIS assessments and clinical measurements.

{
  "resourceType": "Observation",
  "id": "oasis_m1800_123",
  "status": "final",
  "code": {
    "coding": [{
      "system": "https://www.cms.gov/oasis",
      "code": "M1800",
      "display": "Grooming"
    }]
  },
  "subject": {
    "reference": "Patient/pat_123456789"
  },
  "effectiveDateTime": "2024-01-15T10:00:00Z",
  "valueCodeableConcept": {
    "coding": [{
      "system": "https://www.cms.gov/oasis/m1800",
      "code": "0",
      "display": "Able to groom self unaided"
    }]
  },
  "meta": {
    "profile": ["http://nestmed.com/fhir/StructureDefinition/oasis-observation"]
  },
  "extension": [{
    "url": "http://nestmed.com/fhir/extensions/oasis-timing",
    "valueCode": "SOC"
  }]
}

QuestionnaireResponse

Resource: QuestionnaireResponse Endpoint: /v1/QuestionnaireResponse Source: OASIS assessmentsCaptures complete OASIS assessment responses.

{
  "resourceType": "QuestionnaireResponse",
  "id": "oasis_soc_456",
  "questionnaire": "http://nestmed.com/fhir/Questionnaire/oasis-e-soc",
  "status": "completed",
  "subject": {
    "reference": "Patient/pat_123456789"
  },
  "authored": "2024-01-15T10:00:00Z",
  "author": {
    "reference": "Practitioner/clin_987654321"
  },
  "item": [
    {
      "linkId": "M1033",
      "text": "Risk for Hospitalization",
      "answer": [{
        "valueCoding": {
          "system": "https://www.cms.gov/oasis/m1033",
          "code": "1",
          "display": "History of falls"
        }
      }]
    }
  ],
  "extension": [{
    "url": "http://nestmed.com/fhir/extensions/oasis-type",
    "valueCode": "SOC"
  },
  {
    "url": "http://nestmed.com/fhir/extensions/hhrg-code",
    "valueString": "2BA2S"
  }]
}

Clinical Resources

MedicationStatement

Resource: MedicationStatement Endpoint: Accessed via /v1/List Source: Visit medicationsPatient medication records with custom extensions.

{
  "resourceType": "MedicationStatement",
  "id": "med_statement_123",
  "status": "active",
  "medicationCodeableConcept": {
    "text": "Metformin 500mg"
  },
  "subject": {
    "reference": "Patient/pat_123456789"
  },
  "dosage": [{
    "text": "500mg twice daily oral"
  }],
  "extension": [{
    "url": "https://nestmed.com/fhir/extensions/clinician-reviewed",
    "valueBoolean": true
  }]
}

CarePlan

Resource: CarePlan Endpoint: /v1/CarePlan Source: Interventions and goalsCare planning and intervention documentation.

{
  "resourceType": "CarePlan",
  "id": "careplan_456",
  "status": "active",
  "intent": "plan",
  "subject": {
    "reference": "Patient/pat_123456789"
  },
  "activity": [{
    "detail": {
      "code": {
        "text": "Wound care - daily dressing change"
      },
      "status": "in-progress"
    }
  }]
}

DiagnosticReport

Resource: DiagnosticReport Endpoint: /v1/DiagnosticReport Source: Media derivatives (transcripts, captions)Processed documentation from audio/image analysis.

Documentation Resources

DocumentReference

Resource: DocumentReference Endpoint: /v1/DocumentReference Source: Media files and uploaded documentsReferences to binary content (audio, images, PDFs).

{
  "resourceType": "DocumentReference",
  "id": "doc_789",
  "status": "current",
  "type": {
    "text": "Audio Recording"
  },
  "content": [{
    "attachment": {
      "contentType": "audio/mpeg",
      "url": "Binary/media_123"
    }
  }]
}

List

Resource: List Endpoint: /v1/List Source: Medication lists, problem listsCurated collections of resources.

Data Mapping Strategy

Internal to FHIR Transformation

Our facade API transforms internal data structures to FHIR resources:

Search Operations

The FHIR API supports comprehensive search parameters tailored for home health workflows:

Patient Search

# Search by name
GET /fhir/r4/v1/Patient?name=John

# Search by identifier
GET /fhir/r4/v1/Patient?identifier=MRN-12345

# Search by birthdate
GET /fhir/r4/v1/Patient?birthdate=1945-03-15

# Search by Medicare Beneficiary ID
GET /fhir/r4/v1/Patient?identifier=http://hl7.org/fhir/sid/us-mbi|1EG4-TE5-MK73

Encounter Search

# Search by patient
GET /fhir/r4/v1/Encounter?patient=Patient/pat_123

# Search by date range
GET /fhir/r4/v1/Encounter?date=ge2024-12-01&date=le2024-12-31

# Search by home health visit type
GET /fhir/r4/v1/Encounter?service-type=home-health&class=HH

# Search for specific visit types
GET /fhir/r4/v1/Encounter?type=http://nestmed.com/visit-type|SOC

OASIS-Specific Searches

# Search for OASIS observations
GET /fhir/r4/v1/Observation?category=oasis&date=2024-01-01

# Search for specific OASIS items
GET /fhir/r4/v1/Observation?code=https://www.cms.gov/oasis|M1800

# Search for SOC assessments
GET /fhir/r4/v1/QuestionnaireResponse?questionnaire=oasis-e-soc&status=completed

Service Request Search

# Active Plan of Care orders
GET /fhir/r4/v1/ServiceRequest?category=plan-of-care&status=active

# Orders within certification period
GET /fhir/r4/v1/ServiceRequest?authored=ge2024-01-01&authored=le2024-02-29

Chained Search

# Find encounters for patients named "Doe"
GET /fhir/r4/v1/Encounter?patient.name=Doe

# Find observations for active episodes
GET /fhir/r4/v1/Observation?encounter.episode-of-care.status=active

# Find conditions for patients in specific PDGM group
GET /fhir/r4/v1/Condition?_has:Extension:url=pdgm-clinical-group&value=MMTA-Wounds

Bundle Operations

Retrieve multiple resources through search operations that return bundles:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "pat_123"
      }
    },
    {
      "resource": {
        "resourceType": "Encounter",
        "id": "visit_456"
      }
    }
  ]
}

Bulk Data Export

Support for regulatory reporting and quality measures:

OASIS Bulk Export

# Export all OASIS assessments for a time period
POST /fhir/r4/v1/$export
Content-Type: application/fhir+json

{
  "_type": "Observation,QuestionnaireResponse",
  "_typeFilter": "Observation?category=oasis,QuestionnaireResponse?questionnaire=oasis-e",
  "_since": "2024-01-01T00:00:00Z",
  "_outputFormat": "ndjson"
}

Quality Reporting Export

# Export data for HHCAHPS and quality measures
POST /fhir/r4/v1/$export
Content-Type: application/fhir+json

{
  "_type": "Patient,Encounter,Observation,Condition",
  "_typeFilter": "Encounter?class=HH&status=finished",
  "_since": "2024-01-01T00:00:00Z",
  "_elements": "id,status,period,type,subject,participant"
}

Capability Statement

Discover API capabilities:

GET /fhir/r4/v1/metadata

Returns a CapabilityStatement resource describing:

Supported resources including home health specific profiles
OASIS-specific search parameters
Bulk export operations
Custom extensions for PDGM and Medicare compliance

Content Negotiation

The API supports standard FHIR content types:

Accept: application/fhir+json
Accept: application/fhir+xml
Accept: application/json
Accept: application/xml

Error Handling

FHIR-compliant error responses using OperationOutcome:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "not-found",
    "details": {
      "text": "Patient with ID 'pat_999' not found"
    },
    "diagnostics": "Resource not found in agency scope"
  }]
}

Getting Started

Endpoints

Base URL

Authentication

Supported Resources

Core Clinical Resources

Home Health Specific Resources

Clinical Resources

Documentation Resources

Data Mapping Strategy

Internal to FHIR Transformation

Search Operations

Patient Search

Encounter Search

OASIS-Specific Searches

Service Request Search

Chained Search

Bundle Operations

Bulk Data Export

OASIS Bulk Export

Quality Reporting Export

Capability Statement

Content Negotiation

Error Handling

Getting Started

Endpoints

​Base URL

​Authentication

​Supported Resources

​Core Clinical Resources

​Home Health Specific Resources

​Clinical Resources

​Documentation Resources

​Data Mapping Strategy

​Internal to FHIR Transformation

​Search Operations

​Patient Search

​Encounter Search

​OASIS-Specific Searches

​Service Request Search

​Chained Search

​Bundle Operations

​Bulk Data Export

​OASIS Bulk Export

​Quality Reporting Export

​Capability Statement

​Content Negotiation

​Error Handling

Base URL

Authentication

Supported Resources

Core Clinical Resources

Home Health Specific Resources

Clinical Resources

Documentation Resources

Data Mapping Strategy

Internal to FHIR Transformation

Search Operations

Patient Search

Encounter Search

OASIS-Specific Searches

Service Request Search

Chained Search

Bundle Operations

Bulk Data Export

OASIS Bulk Export

Quality Reporting Export

Capability Statement

Content Negotiation

Error Handling