Patient

Overview

The Patient resource provides demographics and administrative information about individuals receiving care or health-related services. This resource serves as the central identity for most clinical and administrative workflows in the Netsmart General Purpose R4 API.

Important: Always validate Patient resource support and available operations by retrieving the current CapabilityStatement from /metadata before implementing integrations.

Resource Schema

The Patient resource follows the HL7 FHIR R4 Patient specification with Netsmart-specific extensions for enhanced demographic data.

Key elements include:

identifier - Patient identifiers (MRN, SSN, etc.)
name - Patient names (current and historical)
gender - Administrative gender
birthDate - Date of birth
address - Patient addresses
telecom - Contact information
extension - Netsmart-specific demographic extensions

Example Patient Resource

{
  "resourceType": "Patient",
  "id": "12345",
  "identifier": [
    {
      "system": "http://hl7.org/fhir/sid/us-ssn",
      "value": "123456789"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Smith",
      "given": ["John", "Michael"]
    }
  ],
  "gender": "male",
  "birthDate": "1990-01-15",
  "address": [
    {
      "use": "home",
      "line": ["123 Main St"],
      "city": "Anytown",
      "state": "CA",
      "postalCode": "12345"
    }
  ]
}

Supported Profiles

This API supports the following FHIR profiles:

HL7 FHIR R4 Patient

Operations

The General Purpose FHIR R4 Patient resource supports the following standard operations. However, support varies by the targeted CareRecord or solution.

CareRecord / Solution	Create	Read	Update	Search
GEHRIMED	-	Yes	-	Yes
myAvatar	Yes	Yes	Yes	Yes
myEvolv	-	Yes	-	Yes
myUnity	-	Yes	-	Yes
Referral Manager	Yes	-	Yes	-

Search

info

Not all Netsmart solutions support Patient search. See supported operations table above and consult your target solution's documentation for more information.

This resource supports a combination of standard and custom search parameters in addition to the common parameters.

Standard Parameters

Name	Type	Description
birthdate	date	The patient's date of birth
death-date	date	The date of death has been provided and satisfies this search value
family	string	A portion of the family name of the patient
gender	token	Administrative Gender of the patient
given	string	A portion of the given name of the patient
identifier	token	A patient identifier
name	string	A server defined search that may match any of the string fields in the HumanName, including family, give, prefix, suffix, suffix, and/or text
_id	id	Unique identifier of the Patient. Cannot be used with other search parameters.
_text	string	Functionally equivalent to the `name` parameter.

Custom Parameters

Name	Type	Description
alias	string	The standard name search parameters above only allow searching on the patient's current name. Use this parameter to search their `old` names instead.
cin	special	The patient's Medi-Cal Number. Only supported by myAvatar with Cal-PM.
end	date	Deprecated. Use `birthdate` parameter with `le` prefix instead.
location	special	Unique identifier of the location. This parameter may only be used in combination with `_text` and common search parameters This support a specific integration and is not necessarily supported for all use cases and CareRecords.
ssn	string	Deprecated. Use `identifier` parameters with the `http://hl7.org/fhir/sid/us-ssn` system. Example: `identifier=http://hl7.org/fhir/sid/us-ssn\|123456789`
start	date	Deprecated. Use `birthdate` parameter with `ge` prefix instead.

Search Examples

The POST method is recommended as it keeps health information out of the URL.

Production
Preview

Search by Date of Birth
curl -X POST https://fhir.netsmartcloud.com/v4/Patient/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "birthdate=ge1996-03-28" \
    -d "birthdate=le1996-03-30"

Search by US Social Security Number
curl -X POST https://fhir.netsmartcloud.com/v4/Patient/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "identifier=http://hl7.org/fhir/sid/us-ssn|123456789"

Search by Date of Birth
curl -X POST https://fhirtest.netsmartcloud.com/v4/Patient/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "birthdate=ge1996-03-28" \
    -d "birthdate=le1996-03-30"

Search by US Social Security Number
curl -X POST https://fhirtest.netsmartcloud.com/v4/Patient/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "identifier=http://hl7.org/fhir/sid/us-ssn|123456789"

Extended Operations

In addition to the standard operations described above, we have also implemented extended operations on the Patient resource. Some are experimental and are not supported by most CareRecords and solutions yet.

CareRecord / Solution	$assign-mrn	$match	$merge	$unmerge
GEHRIMED	-	-	-	-
myAvatar	Yes	-	-	-
myEvolv	-	-	-	-
myUnity	-	-	-	-
Referral Manager	-	-	Yes	-

Assign Permanent MRN ($assign-mrn)

The Patient Assign Permanent MRN operation is used with the myAvatar CareRecord to assign a permanent medical record number (MRN) to a Call Intake Patient.

Match ($match)

Experimental

This is an experimental operation within CareConnect that is not yet supported by any Netsmart CareRecord or other solution.

The Patient Match operation provides an alternative searching using MPI based logic and is based on the HL7 FHIR R4 Patient Match Operation specification.

Merge ($merge)

info

Not all Netsmart solutions support Patient merge via CareConnect. See supported extended operations table above and consult your target solution's documentation for more information.

The Patient Merge operation allows for merging duplicate patients and is based on the draft HL7 FHIR Patient Merge Operation.

Unmerge ($unmerge)

Experimental

This is an experimental operation within CareConnect that is not yet supported by any Netsmart CareRecord or other solution.

The Patient Unmerge operation is an experimental operation to allow for reversing a previous merge operation based loosely on the draft HL7 FHIR Patient Merge Operation.

Special Considerations

The General Purpose API FHIR R4 Patient resource has the following considerations in addition to the shared special considerations.

Administrative Gender and the HL7 Gender Identity Extension

info

We will be enhancing our handling of Sexual Orientation and Gender Identity content in alignment with the Gender Harmony Project in our newer APIs. This API is unchanged to sustain existing integrations for backwards compatibility.

In order to support a more expansive list of gender values this API and resource prioritizes the HL7 Gender Identity Extension to pass gender into the supported CareRecords over the Patient Administrative Gender. This can produce some unanticipated results in some use cases.

Other Administrative Gender Code

The Administrative Gender will be set to other in Read and Search results when recorded as other, transgender-female, or transgender-male within the CareRecord.

Netsmart myEvolv does not currently support the other Administrative Gender on create or update. Applications must specify the details using the HL7 Gender Identity Extension.

Unsupported HL7 Gender Identity Codes

The non-binary and non-disclose codes are not currently supported with CareRecords using this extension. myEvolv does not support the other code as well.

HL7 Gender Identity Extension Sets Gender on Create and Update

On create or update the HL7 Gender Identity Extension will determine the Gender value set in the CareRecord rather than the Administrative Gender.

Call Intake Patient Demographics

Call Intake patients in myAvatar are accessible via the Patient resource alongside those with Permanent MRNs. However, the Call Intake patients support a limited set of demographic information. Use the Assign Permanent MRN extended operation to change the Patient type and add support for additional content.

Error Handling

For information about error responses when working with Patient resources, see Common Errors.

Common Patient-related errors include:

Invalid patient identifiers
Unsupported search parameters
Missing required demographic fields
Gender identity extension conflicts

Integration Patterns

Patient-Centric Workflows

Most clinical resources reference Patient as the subject:

# Search for patient's conditions
curl -X GET "https://fhir.netsmartcloud.com/v4/Condition?patient=12345" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

# Search for patient's encounters
curl -X GET "https://fhir.netsmartcloud.com/v4/Encounter?patient=12345" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Include Parameters

Retrieve related resources with Patient searches:

# Include patient's general practitioner
curl -X GET "https://fhir.netsmartcloud.com/v4/Patient?_include=Patient:general-practitioner" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Relationships to Other Resources

The Patient resource connects to many other resources in the API:

Encounter - Patient care encounters and visits
Condition - Patient diagnoses and health conditions
Observation - Patient vital signs and lab results
MedicationRequest - Patient prescriptions
AllergyIntolerance - Patient allergies
CarePlan - Patient care plans
Coverage - Patient insurance coverage
Practitioner - Patient's care providers

Support

For questions about Patient resource implementation or demographic data handling, contact Netsmart support through your designated support channels.

Overview​

Resource Schema​

Example Patient Resource​

Supported Profiles​

Operations​

Search​

Standard Parameters​

Custom Parameters​

Search Examples​

Extended Operations​

Assign Permanent MRN ($assign-mrn)​

Match ($match)​

Merge ($merge)​

Unmerge ($unmerge)​

Special Considerations​

Administrative Gender and the HL7 Gender Identity Extension​

Other Administrative Gender Code​

Unsupported HL7 Gender Identity Codes​

HL7 Gender Identity Extension Sets Gender on Create and Update​

Call Intake Patient Demographics​

Error Handling​

Integration Patterns​

Patient-Centric Workflows​

Include Parameters​

Relationships to Other Resources​

Support​

Overview

Resource Schema

Example Patient Resource

Supported Profiles

Operations

Search

Standard Parameters

Custom Parameters

Search Examples

Extended Operations

Assign Permanent MRN ($assign-mrn)

Match ($match)

Merge ($merge)

Unmerge ($unmerge)

Special Considerations

Administrative Gender and the HL7 Gender Identity Extension

Other Administrative Gender Code

Unsupported HL7 Gender Identity Codes

HL7 Gender Identity Extension Sets Gender on Create and Update

Call Intake Patient Demographics

Error Handling

Integration Patterns

Patient-Centric Workflows

Include Parameters

Relationships to Other Resources

Support