Patient

Overview

The Patient resource represents individuals receiving healthcare services within the Provider System Access API. Patients are the central focus of healthcare delivery and the primary subject of clinical observations, encounters, and care plans.

Key Use Cases:

• Retrieve patient demographic information
• Access patient contact details and identifiers
• Query patient records by name or identifier
• Support patient-centered care coordination

Relationships to Other Resources:

• Encounter - Healthcare encounters and visits for the patient
• Observation - Clinical observations and measurements about the patient
• Practitioner - Healthcare providers caring for the patient
• Organization - Healthcare organizations providing care to the patient

Resource Schema

Key fields in the Patient resource:

{
  "resourceType": "Patient",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/patient-id",
      "value": "patient-123"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "string",
      "given": ["string"],
      "prefix": ["Mr.", "Ms.", "Dr."],
      "suffix": ["Jr.", "Sr.", "III"]
    }
  ],
  "telecom": [
    {
      "system": "phone|email|fax",
      "value": "string",
      "use": "home|work|mobile"
    }
  ],
  "gender": "male|female|other|unknown",
  "birthDate": "YYYY-MM-DD",
  "deceasedBoolean": false,
  "deceasedDateTime": "YYYY-MM-DDTHH:mm:ssZ",
  "address": [
    {
      "use": "home|work|temp",
      "line": ["string"],
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string"
    }
  ],
  "maritalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus",
        "code": "M",
        "display": "Married"
      }
    ]
  },
  "contact": [
    {
      "relationship": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
              "code": "C",
              "display": "Emergency Contact"
            }
          ]
        }
      ],
      "name": {
        "family": "string",
        "given": ["string"]
      },
      "telecom": [
        {
          "system": "phone",
          "value": "string"
        }
      ]
    }
  ]
}

Key Fields:

• id - Unique identifier for the patient
• identifier - External identifiers (MRN, SSN, insurance member ID)
• name - Patient's name components
• telecom - Contact information
• gender - Administrative gender
• birthDate - Date of birth
• address - Patient addresses

Operations

Read

Retrieve a specific patient by ID.

Production

GET /Patient/{id}

Example Request

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

Preview

GET /Patient/{id}

Example Request

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

Search

Search for patients using various criteria.

GET Method

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

Production

GET /Patient?parameter=value

Preview

GET /Patient?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production

POST /Patient/_search

Preview

POST /Patient/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
birthdate	date	No	Patient's birth date	birthdate=1990-01-15
death-date	date	No	Patient's death date	death-date=2023-12-01
family	string	No	Family (last) name	family=Smith
gender	token	No	Administrative gender	gender=female
given	string	No	Given (first) name	given=John
identifier	token	No	Patient identifier	identifier=12345
name	string	No	Any part of patient name	name=John Smith

Common Search Patterns

Find patients by last name:

GET /Patient?family=Smith&_count=10

Search by full name:

GET /Patient?name=John Smith

Find by identifier:

GET /Patient?identifier=12345

Search by birth date range:

GET /Patient?birthdate=ge1990-01-01&birthdate=le1995-12-31

Find by gender:

GET /Patient?gender=female&_count=20

Examples

Request Examples

Production

Search by family name

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

Search by identifier

curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Patient/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "identifier=12345"

Search by birth date

curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Patient/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "birthdate=1990-01-15"

Preview

Search by family name

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

Search by identifier

curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Patient/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "identifier=12345"

Search by birth date

curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Patient/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "birthdate=1990-01-15"

Response Examples

Successful Search Response

Patient Search Bundle

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "patient-123",
        "identifier": [
          {
            "system": "http://example.org/patient-id",
            "value": "patient-123"
          },
          {
            "system": "http://example.org/mrn",
            "value": "MRN-456789"
          }
        ],
        "active": true,
        "name": [
          {
            "use": "official",
            "family": "Smith",
            "given": ["John", "Michael"],
            "prefix": ["Mr."]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "(916) 555-0123",
            "use": "home"
          },
          {
            "system": "email",
            "value": "john.smith@example.com",
            "use": "home"
          }
        ],
        "gender": "male",
        "birthDate": "1990-01-15",
        "address": [
          {
            "use": "home",
            "line": ["123 Main Street"],
            "city": "Sacramento",
            "state": "CA",
            "postalCode": "95814",
            "country": "US"
          }
        ]
      }
    }
  ]
}

Individual Patient Response

Single Patient Resource

{
  "resourceType": "Patient",
  "id": "patient-456",
  "identifier": [
    {
      "system": "http://example.org/patient-id",
      "value": "patient-456"
    },
    {
      "system": "http://example.org/insurance-member-id",
      "value": "INS-789012"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Johnson",
      "given": ["Sarah", "Elizabeth"],
      "prefix": ["Ms."]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "(415) 555-0199",
      "use": "mobile"
    }
  ],
  "gender": "female",
  "birthDate": "1985-07-22",
  "address": [
    {
      "use": "home",
      "line": ["456 Oak Avenue", "Apt 2B"],
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    }
  ],
  "maritalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus",
        "code": "M",
        "display": "Married"
      }
    ]
  },
  "contact": [
    {
      "relationship": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
              "code": "C",
              "display": "Emergency Contact"
            }
          ]
        }
      ],
      "name": {
        "family": "Johnson",
        "given": ["Michael"]
      },
      "telecom": [
        {
          "system": "phone",
          "value": "(415) 555-0200"
        }
      ]
    }
  ]
}

Empty Result Set

No Patients Found

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

Integration Patterns

Common Workflows

1. Patient Demographics Lookup

# Step 1: Search for patient by identifier
GET /Patient?identifier=12345

# Step 2: Get specific patient details
GET /Patient/patient-123

# Step 3: Find related encounters
GET /Encounter?patient=Patient/patient-123

2. Patient Search and Verification

# Step 1: Search by name and birth date
GET /Patient?family=Smith&given=John&birthdate=1990-01-15

# Step 2: Verify patient identity
GET /Patient/patient-123

# Step 3: Get patient's recent observations
GET /Observation?patient=Patient/patient-123&_count=5

Related Resources

• Encounter - Healthcare encounters and visits for the patient
• Observation - Clinical observations and measurements about the patient
• Practitioner - Healthcare providers caring for the patient
• Organization - Healthcare organizations providing care to the patient

Include Parameters

Use _include and _revinclude to fetch related resources:

# Get patient with their encounters
GET /Patient?family=Smith&_revinclude=Encounter:patient

# Get patient with recent observations
GET /Patient?identifier=12345&_revinclude=Observation:patient

Error Handling

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

Patient-Specific Error Scenarios

• 404 Not Found: Patient ID doesn't exist or patient record is inactive
• 400 Bad Request: Invalid search parameters or malformed date formats
• Empty Results: No patients match the search criteria

Troubleshooting Tips

• No Results for Name Search: Try searching with partial names or different name components
• Date Format Issues: Ensure birth dates are in YYYY-MM-DD format
• Identifier Problems: Verify identifier format and system values
• Performance Issues: Use _count parameter to limit result sets

Supported Profiles

• HL7 FHIR R4 Patient
• US Core Patient