Social Determinants of Health (SDOH) in FHIR: The Gravity Project Implementation Guide

A patient with uncontrolled diabetes visits their physician every three months. Medications are adjusted. Lab work is ordered. Yet their A1C never improves. The reason has nothing to do with medicine — they can't afford the healthy food their care plan requires, and they live in a food desert with no grocery store within 10 miles.

This is the SDOH problem. Social determinants of health — food insecurity, housing instability, transportation barriers, social isolation, and interpersonal safety — have a powerful influence on health outcomes and health inequities, according to the WHO, which notes that they can outweigh genetic influences or healthcare access. Yet most EHR systems have no structured way to capture, code, or act on this data.

When you are ready to implement it, our FHIR integration team covers the build, testing and go-live.

Related Reading

For more insights, explore our guides on Interoperability's Next Frontier: SDOH & Behavioral Health and FHIR in Modern Healthcare.

You may also find value in our EHR Software Development Guide and Building a Healthtech App.

The Gravity Project, an HL7 FHIR Accelerator initiative, has built the definitive FHIR implementation guide for SDOH data. It defines profiles, value sets, and workflows for screening patients, documenting social needs, making referrals to community organizations, and tracking outcomes — all using standard FHIR resources. As of 2026, CMS quality measures increasingly require SDOH screening data, making this implementation not just clinically valuable but regulatory necessary.

The Gravity Project: SDOH in FHIR

The Gravity Project SDOH Clinical Care Implementation Guide (HL7 IG; the current published version is SDOH Clinical Care IG v3.0.0 (STU 3)) defines how to represent SDOH data across the entire clinical workflow: screening, assessment, diagnosis, goal-setting, referral, and outcome tracking.

Core FHIR Resources

SDOH Screening Tools and FHIR Mapping

The two most widely adopted SDOH screening tools are the AHC HRSN (Accountable Health Communities Health-Related Social Needs) screening tool and PRAPARE (Protocol for Responding to and Assessing Patients' Assets, Risks, and Experiences).

AHC HRSN Screening Tool

The CMS-developed AHC HRSN tool screens for five core domains and has standard LOINC panel codes:

Representing Screening Responses as FHIR Observations

{
  "resourceType": "Observation",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/sdoh-clinicalcare/StructureDefinition/SDOHCC-ObservationScreeningResponse"
    ]
  },
  "status": "final",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
          "code": "social-history",
          "display": "Social History"
        }
      ]
    },
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
          "code": "survey",
          "display": "Survey"
        }
      ]
    },
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-category",
          "code": "sdoh",
          "display": "SDOH"
        }
      ]
    },
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/sdoh-clinicalcare/CodeSystem/SDOHCC-CodeSystemTemporaryCodes",
          "code": "food-insecurity",
          "display": "Food Insecurity"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "88122-7",
        "display": "Within the past 12 months we worried whether our food would run out before we got money to buy more"
      }
    ]
  },
  "subject": {
    "reference": "Patient/patient-john-smith"
  },
  "effectiveDateTime": "2026-03-16T10:30:00Z",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "LA28397-0",
        "display": "Often true"
      }
    ]
  },
  "derivedFrom": [
    {
      "reference": "QuestionnaireResponse/ahc-hrsn-response-001"
    }
  ]
}

From Screening to Diagnosis: SDOH Conditions

When a screening identifies a social need, the next step is documenting it as a FHIR Condition using SDOH-specific SNOMED CT and ICD-10-CM codes. A positive screening answer is a reported need. A clinician or care team member assesses it, and only then may it be recorded as a Condition (health concern or problem). That is why the example below has an asserter: the person who made the assessment.

SDOH Condition Codes

FHIR Condition Example

{
  "resourceType": "Condition",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/sdoh-clinicalcare/StructureDefinition/SDOHCC-Condition"
    ]
  },
  "clinicalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
        "code": "active"
      }
    ]
  },
  "verificationStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
        "code": "confirmed"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/condition-category",
          "code": "health-concern",
          "display": "Health Concern"
        }
      ]
    },
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-category",
          "code": "sdoh",
          "display": "SDOH"
        }
      ]
    },
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/sdoh-clinicalcare/CodeSystem/SDOHCC-CodeSystemTemporaryCodes",
          "code": "food-insecurity",
          "display": "Food Insecurity"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "733423003",
        "display": "Food insecurity"
      },
      {
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "code": "Z59.41",
        "display": "Food insecurity"
      }
    ]
  },
  "subject": {
    "reference": "Patient/patient-john-smith"
  },
  "onsetDateTime": "2026-03-16",
  "asserter": {
    "reference": "Practitioner/dev-practitioner"
  },
  "evidence": [
    {
      "detail": [
        {
          "reference": "Observation/ahc-hrsn-food-screening-001"
        }
      ]
    }
  ]
}

The Referral Workflow: ServiceRequest, Task, and Community Integration

Identifying an SDOH need is only the beginning. The clinical value comes from connecting patients to community resources — food banks, housing assistance programs, transportation services — and tracking whether those referrals result in improved outcomes.

ServiceRequest: Making the Referral

{
  "resourceType": "ServiceRequest",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/sdoh-clinicalcare/StructureDefinition/SDOHCC-ServiceRequest"
    ]
  },
  "status": "active",
  "intent": "order",
  "category": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/sdoh-clinicalcare/CodeSystem/SDOHCC-CodeSystemTemporaryCodes",
          "code": "food-insecurity",
          "display": "Food Insecurity"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "467771000124109",
        "display": "Assistance with application for food pantry program"
      }
    ]
  },
  "subject": {
    "reference": "Patient/patient-john-smith"
  },
  "requester": {
    "reference": "Practitioner/dev-practitioner"
  },
  "performer": [
    {
      "reference": "Organization/local-food-bank-org"
    }
  ],
  "reasonReference": [
    {
      "reference": "Condition/food-insecurity-condition-001"
    }
  ],
  "occurrencePeriod": {
    "start": "2026-03-16",
    "end": "2026-06-16"
  },
  "note": [
    {
      "text": "Patient reports running out of food regularly. Referred for SNAP enrollment assistance and food pantry access."
    }
  ]
}

Task: Tracking Referral Progress

The Task resource tracks the lifecycle of an SDOH referral from creation to completion:

{
  "resourceType": "Task",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/sdoh-clinicalcare/StructureDefinition/SDOHCC-TaskForReferralManagement"
    ]
  },
  "status": "in-progress",
  "intent": "order",
  "code": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/CodeSystem/task-code",
        "code": "fulfill",
        "display": "Fulfill the focal request"
      }
    ]
  },
  "focus": {
    "reference": "ServiceRequest/sdoh-referral-food-001"
  },
  "for": {
    "reference": "Patient/patient-john-smith"
  },
  "requester": {
    "reference": "Organization/requesting-clinic"
  },
  "owner": {
    "reference": "Organization/local-food-bank-org"
  },
  "businessStatus": {
    "text": "Patient contacted, appointment scheduled for 2026-03-22"
  },
  "authoredOn": "2026-03-16T11:00:00Z",
  "lastModified": "2026-03-17T09:15:00Z",
  "output": [
    {
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/sdoh-clinicalcare/CodeSystem/SDOHCC-CodeSystemTemporaryCodes",
            "code": "resulting-activity",
            "display": "Resulting Activity"
          }
        ]
      },
      "valueReference": {
        "reference": "Procedure/snap-enrollment-procedure-001"
      }
    }
  ]
}

Closing the loop: referral outcomes and declined sharing

A referral is only closed when the care team learns what happened. The community organization (CBO) reports back by changing the Task status and, when it finishes, by pointing Task.output at what it did.

When the patient declines to share data with the CBO, do not send the ServiceRequest. Record the decision as a Consent with provision.type set to deny for that organization, and give the patient the resource information directly instead.

# Route a referral Task update from the community organization
def route_task_update(task):
    status = task["status"]
    if status in ("rejected", "cancelled", "failed"):
        return "care-team-queue"   # CBO declined or could not help: a person picks a new option
    if status == "completed":
        return "record-outcome"    # read Task.output (Procedure or Observation)
    if status in ("received", "accepted", "in-progress", "on-hold"):
        return "track"
    return "review"                # any status we did not plan for gets a human look

Test it: an integration test sends a Task with status rejected and asserts that the referral returns to the care team queue.

Community Referral Platform Integration

The Gravity Project defines a Coordination Platform (CP) architecture that connects healthcare organizations with community-based organizations (CBOs). Several platforms implement this pattern:

• Unite Us — Closed-loop referral network with FHIR API integration
• Aunt Bertha (findhelp) — Community resource directory with referral tracking
• NowPow — Prescription-based social care referral platform
• 211/AIRS — National community resource information network

Examples, not endorsements; product names as listed when this guide was written.

Integration Pattern

"""SDOH referral workflow implementation."""
import json
import requests
from datetime import datetime

class SDOHReferralManager:
    def __init__(self, fhir_base_url, auth_token):
        self.fhir_url = fhir_base_url.rstrip("/")
        self.headers = {
            "Authorization": f"Bearer {auth_token}",
            "Content-Type": "application/fhir+json",
            "Accept": "application/fhir+json",
        }

    def create_screening_observations(self, patient_id, screening_responses):
        """Create FHIR Observations from screening tool responses."""
        observations = []
        for response in screening_responses:
            obs = {
                "resourceType": "Observation",
                "status": "final",
                "category": [
                    {
                        "coding": [{
                            "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                            "code": "social-history"
                        }]
                    },
                    {
                        "coding": [{
                            "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                            "code": "survey"
                        }]
                    },
                    {
                        "coding": [{
                            "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-category",
                            "code": "sdoh"
                        }]
                    }
                ],
                "code": {
                    "coding": [{
                        "system": "http://loinc.org",
                        "code": response["loinc_code"],
                        "display": response["question"]
                    }]
                },
                "subject": {"reference": f"Patient/{patient_id}"},
                "effectiveDateTime": datetime.utcnow().isoformat() + "Z",
                "valueCodeableConcept": {
                    "coding": [{
                        "system": "http://loinc.org",
                        "code": response["answer_code"],
                        "display": response["answer_display"]
                    }]
                }
            }
            resp = requests.post(
                f"{self.fhir_url}/Observation",
                json=obs, headers=self.headers
            )
            resp.raise_for_status()
            observations.append(resp.json())
        return observations

    def create_sdoh_condition(self, patient_id, domain, snomed_code,
                              snomed_display, evidence_obs_ids,
                              asserter=None, verification_status="provisional"):
        """Record an assessed SDOH Condition.

        A positive screening answer is a reported need, not a diagnosis.
        Call this only after a clinician or care team member has assessed it,
        and pass that person as asserter (for example "Practitioner/123").
        """
        if not asserter:
            raise ValueError("asserter is required: a person must assess the need first")
        condition = {
            "resourceType": "Condition",
            "clinicalStatus": {
                "coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active"}]
            },
            "verificationStatus": {
                "coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status", "code": verification_status}]
            },
            "category": [
                {"coding": [{"system": "http://hl7.org/fhir/us/core/CodeSystem/condition-category", "code": "health-concern"}]},
                {"coding": [{"system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-category", "code": "sdoh"}]},
                {"coding": [{"system": "http://hl7.org/fhir/us/sdoh-clinicalcare/CodeSystem/SDOHCC-CodeSystemTemporaryCodes", "code": domain}]}
            ],
            "code": {
                "coding": [{
                    "system": "http://snomed.info/sct",
                    "code": snomed_code,
                    "display": snomed_display
                }]
            },
            "subject": {"reference": f"Patient/{patient_id}"},
            "onsetDateTime": datetime.utcnow().strftime("%Y-%m-%d"),
            "asserter": {"reference": asserter},
            "evidence": [
                {"detail": [{"reference": f"Observation/{obs_id}"}]}
                for obs_id in evidence_obs_ids
            ]
        }
        resp = requests.post(
            f"{self.fhir_url}/Condition",
            json=condition, headers=self.headers
        )
        resp.raise_for_status()
        return resp.json()

    def create_referral(self, patient_id, condition_id,
                        service_snomed, service_display, performer_org_id):
        """Create a ServiceRequest referral to a community org."""
        service_request = {
            "resourceType": "ServiceRequest",
            "status": "active",
            "intent": "order",
            "code": {
                "coding": [{
                    "system": "http://snomed.info/sct",
                    "code": service_snomed,
                    "display": service_display
                }]
            },
            "subject": {"reference": f"Patient/{patient_id}"},
            "performer": [{"reference": f"Organization/{performer_org_id}"}],
            "reasonReference": [{"reference": f"Condition/{condition_id}"}],
        }
        resp = requests.post(
            f"{self.fhir_url}/ServiceRequest",
            json=service_request, headers=self.headers
        )
        resp.raise_for_status()
        return resp.json()

    def track_referral(self, task_id, new_status, business_status_text=None):
        """Update the status of a referral Task."""
        updates = {"status": new_status}
        if business_status_text:
            updates["businessStatus"] = {"text": business_status_text}
        updates["lastModified"] = datetime.utcnow().isoformat() + "Z"

        resp = requests.patch(
            f"{self.fhir_url}/Task/{task_id}",
            json=updates, headers=self.headers
        )
        resp.raise_for_status()
        return resp.json()

Patient Consent for SDOH Data Sharing

SDOH data is sensitive. A patient's food insecurity status or housing situation is personal information that they may not want shared broadly. The Gravity Project defines a Consent resource specifically for SDOH data sharing:

{
  "resourceType": "Consent",
  "status": "active",
  "scope": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/consentscope",
        "code": "patient-privacy"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://loinc.org",
          "code": "59284-0",
          "display": "Consent Document"
        }
      ]
    }
  ],
  "patient": {
    "reference": "Patient/patient-john-smith"
  },
  "dateTime": "2026-03-16T10:45:00Z",
  "policyRule": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/consentpolicycodes",
        "code": "hipaa-auth",
        "display": "HIPAA Authorization"
      }
    ]
  },
  "performer": [
    {
      "reference": "Patient/patient-john-smith"
    }
  ],
  "organization": [
    {
      "reference": "Organization/requesting-clinic"
    }
  ],
  "provision": {
    "type": "permit",
    "period": {
      "start": "2026-03-16",
      "end": "2027-03-16"
    },
    "actor": [
      {
        "role": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
              "code": "IRCP",
              "display": "information recipient"
            }
          ]
        },
        "reference": {
          "reference": "Organization/local-food-bank-org"
        }
      }
    ],
    "action": [
      {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/consentaction",
            "code": "access"
          }
        ]
      }
    ],
    "class": [
      {
        "system": "http://hl7.org/fhir/resource-types",
        "code": "Condition"
      },
      {
        "system": "http://hl7.org/fhir/resource-types",
        "code": "ServiceRequest"
      }
    ]
  }
}

The JSON examples on this page were validated on 15 October 2026 against SDOH Clinical Care IG v3.0.0 (STU 3) with the HL7 FHIR validator (FHIR R4, SNOMED CT US edition).

Quality Measures and Reporting

CMS quality programs are increasingly incorporating SDOH measures. HEDIS 2024+ includes SDOH screening measures, and CMS's health equity strategy prioritizes SDOH data collection:

• HEDIS Social Need Screening and Intervention — Percentage of members screened for food insecurity, housing instability, transportation, utility, and interpersonal safety needs
• CMS Hospital Quality Reporting — Screen for SDOH needs and document in a structured format
• MIPS Quality Measures — SDOH screening is included in multiple MIPS quality measure specifications

For validating that SDOH FHIR resources conform to the Gravity Project profiles, our guide on FHIR resource validation covers the profile validation layer needed for IG conformance.

Plan your SDOH build

Planning SDOH screening and referrals in your EHR? We can map your screening tool to SDOH Clinical Care profiles and test the referral loop. Talk to our FHIR integration team.