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 — account for 30-55% of health outcomes according to the WHO. 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 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) 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/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, you worried that your food would run out"
      }
    ]
  },
  "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.

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/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 assistance 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"
      }
    }
  ]
}

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 — Largest 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

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"
                        }]
                    }
                ],
                "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):
        """Create an SDOH Condition from screening results."""
        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": "confirmed"}]
            },
            "category": [
                {"coding": [{"system": "http://hl7.org/fhir/us/core/CodeSystem/condition-category", "code": "health-concern"}]},
                {"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"),
            "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",
  "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"
      }
    ]
  }
}

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.