Searching Patients

The ESUS FHIR API supports a pragmatic subset of the FHIR search specification: search parameters for the most common clinical and administrative fields, combined filters, and offset-based pagination. Advanced features such as custom search modifiers (:exact, :contains) and chained search are not supported today.

Basic Search

Get all patients (paginated):

curl -X GET https://api.esus.health/fhir/Patient \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (Bundle):

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": [{ "family": "Smith", "given": ["John"] }]
      }
    },
    {
      "resource": {
        "resourceType": "Patient",
        "id": "b8c2d3e4-f5a6-7890-bcde-f01234567890",
        "name": [{ "family": "Johnson", "given": ["Mary"] }]
      }
    }
  ]
}

Search Parameters

By Name

# Find patients with "Smith" in any name field
GET /fhir/Patient?name=Smith

# Search by given name
GET /fhir/Patient?given=John

# Search by family name
GET /fhir/Patient?family=Smith

By Identifier

# Find patient by medical record number or national ID
GET /fhir/Patient?identifier=12345678

By Gender and Birth Date

Birth-date supports the standard FHIR date prefixes (eq, ne, gt, lt, ge, le):

# Male patients born after 1990-01-01
GET /fhir/Patient?gender=male&birthdate=gt1990-01-01

Pagination

Pagination is offset-based. Use _count to control page size and _offset to skip results; prefer following the link.next URL returned in the response to avoid mistakes.

# First page, 20 items
GET /fhir/Patient?_count=20

# Next page (offset by one page)
GET /fhir/Patient?_count=20&_offset=20

Response Links

The Bundle includes navigation links with the exact URLs you should follow:

{
  "link": [
    { "relation": "self", "url": "/fhir/Patient?_count=20&_offset=0" },
    { "relation": "next", "url": "/fhir/Patient?_count=20&_offset=20" }
  ]
}

Common Search Parameters

Parameter	Description
`_id`	Filter by resource id (UUID)
`_count`	Page size (items per response)
`_offset`	Items to skip (for pagination)
`name`	Search by any name component (given, family, text)
`given`	Search by given name
`family`	Search by family name
`gender`	Filter by administrative gender
`birthdate`	Filter by date of birth, with date prefixes
`identifier`	Search by external identifier
`address`	Search by address components

Next Steps

Now learn how to create, update, and delete patients.