Observation

Overview

The Observation resource represents clinical observations and measurements within the Provider Patient Access API. Observations capture vital signs, laboratory results, assessments, and other clinical findings that support healthcare delivery and quality reporting.

Key Use Cases:

• Retrieve patient vital signs and measurements
• Access laboratory test results and diagnostic findings
• Query clinical assessments and survey responses
• Support quality reporting and clinical decision making

Relationships to Other Resources:

• Patient - Observations are made about specific patients
• Encounter - Observations are often recorded during healthcare encounters
• Practitioner - Healthcare providers who perform or interpret observations
• Organization - Healthcare organizations where observations are made

Resource Schema

Key fields in the Observation resource:

{
  "resourceType": "Observation",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/observation-id",
      "value": "obs-123"
    }
  ],
  "status": "registered|preliminary|final|amended|corrected|cancelled|entered-in-error|unknown",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
          "code": "vital-signs|laboratory|procedure|survey|exam|therapy|activity",
          "display": "Vital Signs"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "85354-9",
        "display": "Blood pressure panel with all children optional"
      }
    ]
  },
  "subject": {
    "reference": "Patient/patient-123"
  },
  "encounter": {
    "reference": "Encounter/encounter-456"
  },
  "effectiveDateTime": "2023-12-01T10:30:00Z",
  "valueQuantity": {
    "value": 120,
    "unit": "mmHg",
    "system": "http://unitsofmeasure.org",
    "code": "mm[Hg]"
  }
}

Key Fields:

• id - Unique identifier for the observation
• status - Current state of the observation
• category - Classification of observation type
• code - What was observed (LOINC codes preferred)
• subject - Patient the observation is about
• encounter - Healthcare encounter when observation was made
• effectiveDateTime - When observation was made
• value[x] - Actual result or finding

Operations

Read

Retrieve a specific observation by ID.

Production

GET /Observation/{id}

Example Request

curl -X GET https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Observation/obs-123 \
    -H "Accept: application/fhir+json"

Preview

GET /Observation/{id}

Example Request

curl -X GET https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Observation/obs-123 \
    -H "Accept: application/fhir+json"

Search

Search for observations using various criteria.

GET Method

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

Production

GET /Observation?parameter=value

Preview

GET /Observation?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production

POST /Observation/_search

Preview

POST /Observation/_search

Search Parameters

Patient-based Search:

Parameter	Type	Required	Description	Example
patient	reference	Yes	Patient the observation is about	patient=Patient/patient-123
category	token	No	Observation category	category=vital-signs
code	token	No	Observation code	code=85354-9
date	date	No	Date/time of observation	date=2023-12-01
encounter	reference	No	Encounter when observation was made	encounter=Encounter/encounter-456
status	token	No	Observation status	status=final

ID-based Search:

Parameter	Type	Required	Description	Example
category	token	No	Observation category	category=vital-signs
code	token	No	Observation code	code=85354-9
date	date	No	Date/time of observation	date=2023-12-01
encounter	reference	No	Encounter when observation was made	encounter=Encounter/encounter-456
status	token	No	Observation status	status=final

Common Search Patterns

Find vital signs for a patient:

GET /Observation?patient=Patient/patient-123&category=vital-signs&status=final

Search by observation code:

GET /Observation?code=85354-9&_count=20

Find observations from specific encounter:

GET /Observation?encounter=Encounter/encounter-456

Search by date range:

GET /Observation?patient=Patient/patient-123&date=ge2023-01-01&date=le2023-12-31

Examples

Request Examples

Production

Find patient vital signs

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Observation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&category=vital-signs&_count=10"

Search by observation code

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Observation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "code=85354-9&status=final"

Find laboratory results

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Observation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&category=laboratory&_count=5"

Preview

Find patient vital signs

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Observation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&category=vital-signs&_count=10"

Search by observation code

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Observation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "code=85354-9&status=final"

Find laboratory results

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Observation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&category=laboratory&_count=5"

Response Examples

Successful Search Response

Observation Search Bundle

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "entry": [
    {
      "resource": {
        "resourceType": "Observation",
        "id": "obs-123",
        "identifier": [
          {
            "system": "http://example.org/observation-id",
            "value": "obs-123"
          }
        ],
        "status": "final",
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                "code": "vital-signs",
                "display": "Vital Signs"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "85354-9",
              "display": "Blood pressure panel with all children optional"
            }
          ]
        },
        "subject": {
          "reference": "Patient/patient-123"
        },
        "encounter": {
          "reference": "Encounter/encounter-456"
        },
        "effectiveDateTime": "2023-12-01T10:30:00Z",
        "component": [
          {
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "8480-6",
                  "display": "Systolic blood pressure"
                }
              ]
            },
            "valueQuantity": {
              "value": 120,
              "unit": "mmHg",
              "system": "http://unitsofmeasure.org",
              "code": "mm[Hg]"
            }
          },
          {
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "8462-4",
                  "display": "Diastolic blood pressure"
                }
              ]
            },
            "valueQuantity": {
              "value": 80,
              "unit": "mmHg",
              "system": "http://unitsofmeasure.org",
              "code": "mm[Hg]"
            }
          }
        ]
      }
    }
  ]
}

Individual Observation Response

Single Observation Resource

{
  "resourceType": "Observation",
  "id": "obs-456",
  "identifier": [
    {
      "system": "http://example.org/observation-id",
      "value": "obs-456"
    }
  ],
  "status": "final",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
          "code": "laboratory",
          "display": "Laboratory"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "33747-0",
        "display": "Hemoglobin A1c/Hemoglobin.total in Blood"
      }
    ]
  },
  "subject": {
    "reference": "Patient/patient-123"
  },
  "encounter": {
    "reference": "Encounter/encounter-789"
  },
  "effectiveDateTime": "2023-11-15T08:00:00Z",
  "valueQuantity": {
    "value": 6.5,
    "unit": "%",
    "system": "http://unitsofmeasure.org",
    "code": "%"
  },
  "referenceRange": [
    {
      "low": {
        "value": 4.0,
        "unit": "%"
      },
      "high": {
        "value": 6.0,
        "unit": "%"
      },
      "text": "Normal range for non-diabetic adults"
    }
  ]
}

Empty Result Set

No Observations Found

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "entry": []
}

Integration Patterns

Common Workflows

1. Retrieve Patient Vital Signs

# Step 1: Search for vital signs observations
GET /Observation?patient=Patient/patient-123&category=vital-signs

# Step 2: Get specific observation details
GET /Observation/obs-123

# Step 3: Find related encounter information
GET /Encounter/encounter-456

2. Laboratory Results Review

# Step 1: Find laboratory observations for patient
GET /Observation?patient=Patient/patient-123&category=laboratory

# Step 2: Filter by date range
GET /Observation?patient=Patient/patient-123&category=laboratory&date=ge2023-01-01

# Step 3: Get specific lab result
GET /Observation/obs-456

Related Resources

• Patient - Subjects of observations
• Encounter - Healthcare encounters when observations are made
• Practitioner - Healthcare providers performing observations
• Organization - Healthcare organizations where observations occur

Include Parameters

Use _include to fetch related resources in a single request:

# Get observation with patient information
GET /Observation?code=85354-9&_include=Observation:patient

# Get observation with encounter details
GET /Observation?patient=Patient/patient-123&_include=Observation:encounter

Error Handling

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

Observation-Specific Error Scenarios

• 404 Not Found: Observation ID doesn't exist or has been deleted
• 400 Bad Request: Invalid search parameters or malformed queries
• Empty Results: No observations match the search criteria

Troubleshooting Tips

• Empty Results: Verify patient exists and has observations in the specified date range
• Invalid Parameters: Check parameter names match the FHIR specification
• Performance Issues: Use _count parameter to limit result sets and improve response times

Supported Profiles

• HL7 FHIR R4 Observation
• US Core Observation
• US Core Vital Signs