Guardian Health LogoGuardian Health
AI Compliance Platform Developer Docs

Working with Patients

Build rich patient experiences by retrieving demographics, searching across your roster, and combining patient data with related encounters.

1. Retrieving Patient Records

Use the GET /api/v1/patients/{id} endpoint when you need the most current demographic data for a specific patient.

Fetch a patient

Retrieve an individual patient profile for detail views.

bash
curl "https://api.guardianhealth.dev/api/v1/patients/9e84c63a-2aa7-45d6-a907-5e8bcfa046a1" \\\n  -H "Authorization: Bearer $GUARDIAN_API_KEY"

Patient example

Successful response codes: HTTP 200

application/json
{
  "id": "9e84c63a-2aa7-45d6-a907-5e8bcfa046a1",
  "first_name": "Darius",
  "last_name": "Green",
  "date_of_birth": "1983-11-02",
  "gender": "male",
  "phone": "+1-312-555-9821",
  "medical_record_number": "CE-442918",
  "address": {
    "street": "95 East Ontario St",
    "city": "Chicago",
    "state": "IL",
    "zip_code": "60611",
    "country": "US"
  },
  "created_at": "2024-05-27T13:47:23Z",
  "updated_at": "2024-09-30T21:58:11Z"
}

Patient object fields

Review the structure of the response object. Nested fields are indented to show relationships.

id
string (UUID)Required
Guardian Health patient identifier.
first_name
stringRequired
Legal first name.
last_name
stringRequired
Legal last name.
date_of_birth
string (YYYY-MM-DD)Required
Birth date in ISO format.
gender
string
Gender value (male, female, other, unknown).
medical_record_number
string
Unique MRN for the patient.
address
object
Mailing address fields.
street
string
Street address.
city
string
City of residence.
state
string
State or province code.
zip_code
string
Postal code.
country
string
Country code.
created_at
string (ISO 8601 datetime)
Record creation timestamp.
updated_at
string (ISO 8601 datetime)
Last sync timestamp.

2. Searching for Patients

Combine search parameters to narrow the result set. Guardian Health supports partial name matches and filters such as date of birth and medical record number.

  • Name search: Set the search query parameter to match first or last names.
  • Date of birth: Add date_of_birth for precise filters.
  • Medical record number: Use the MRN value to target a single record quickly.

Search patients

Python example filtering by name and date of birth.

python
import os
import requests

params = {"search": "green", "date_of_birth": "1983-11-02", "limit": 50}
response = requests.get(
    "https://api.guardianhealth.dev/api/v1/patients",
    params=params,
    headers={"Authorization": f"Bearer {os.environ["GUARDIAN_API_KEY"]}"}
)
response.raise_for_status()
print(response.json())

3. Pagination Best Practices

Iterate through large patient rosters by incrementing the offset value. Check the meta.total count to know when you have fetched all pages.

Aggregate paginated patients

JavaScript helper that keeps requesting data until all records are retrieved.

javascript
async function listPatients(limit = 20) {\n  let offset = 0;\n  const results = [];\n  while (true) {\n    const params = new URLSearchParams({ limit: String(limit), offset: String(offset) });\n    const response = await fetch(`https://api.guardianhealth.dev/api/v1/patients?${params.toString()}`, {\n      headers: { Authorization: `Bearer ${process.env.GUARDIAN_API_KEY}` }\n    });\n    if (!response.ok) throw new Error(`Request failed: ${response.status}`);\n    const { data, meta } = await response.json();\n    results.push(...data);\n    if (results.length >= meta.total || data.length === 0) {\n      break;\n    }\n    offset += limit;\n  }\n  return results;\n}

4. Working with Patient Data

Patient records link to encounters, conditions, procedures, and documents. Use these relationships to build holistic care views.

Combine patient and encounter data

Fetch encounters for a patient and build a timeline.

ruby
require 'net/http'\nrequire 'json'\n\n"patient_uri = URI('https://api.guardianhealth.dev/api/v1/patients/c2f1a6fa-4d93-4d37-a8d8-56b6b6a2f94f')"\n"encounters_uri = URI('https://api.guardianhealth.dev/api/v1/encounters?patient_id=c2f1a6fa-4d93-4d37-a8d8-56b6b6a2f94f')"\n\ndef get_json(uri)\n  request = Net::HTTP::Get.new(uri)\n  request['Authorization'] = "Bearer #{ENV['GUARDIAN_API_KEY']}"\n  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }\n  JSON.parse(response.body)\nend\n\npatient = get_json(patient_uri)\nencounters = get_json(encounters_uri)\ntimeline = encounters["data"].map do |encounter|\n  { date: encounter['scheduled_start'], type: encounter['encounter_type'], status: encounter['status'] }\nend\n\nputs JSON.pretty_generate({ patient: patient, timeline: timeline })

5. Patient Privacy and Compliance

  • Guardian Health enforces read-only access—never attempt to modify patient data via the API.
  • Ensure your application complies with HIPAA by restricting access to authorized personnel and logging usage.
  • Implement data retention policies aligned with your organization’s compliance requirements.
  • Only cache patient data for as long as necessary and refresh records frequently to honor EHR updates.