Patient CRUD Operations

CRUD stands for Create, Read, Update, and Delete. This guide covers all four operations for the Patient resource.

Create (POST)

Create a new patient record:

curl -X POST https://api.esus.health/fhir/Patient \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "active": true,
    "name": [
      {
        "use": "official",
        "family": "Williams",
        "given": ["Sarah", "Jane"]
      }
    ],
    "gender": "female",
    "birthDate": "1985-06-20"
  }'

The server returns the created resource with a unique id.

Read (GET)

Retrieve a patient by ID:

curl -X GET https://api.esus.health/fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update (PUT)

Update replaces the entire resource. Include all required fields:

curl -X PUT https://api.esus.health/fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "meta": {
      "versionId": "1",
      "lastUpdated": "2024-01-15T10:30:00Z"
    },
    "active": true,
    "name": [
      {
        "use": "official",
        "family": "Williams",
        "given": ["Sarah", "Jane"]
      }
    ],
    "gender": "female",
    "birthDate": "1985-06-20"
  }'

Patch (PATCH)

PATCH updates specific fields of a resource. The API accepts a partial FHIR Patient object with only the fields you want to change — it does not accept RFC 6902 JSON Patch documents.

curl -X PATCH https://api.esus.health/fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "name": [
      { "use": "official", "family": "Williams", "given": ["Sarah", "Louise"] }
    ]
  }'

The server merges the supplied fields into the existing resource and returns the updated representation.

Delete (DELETE)

curl -X DELETE https://api.esus.health/fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE performs a hard delete: the patient record is removed from the primary table and cannot be read again through the standard GET endpoint. Prior versions may still be accessible via the _history endpoint if history retention is enabled for your plan. A 204 No Content response indicates success.

Version History

Each update creates a new version:

# Get all versions
GET /fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6/_history

# Get a specific version
GET /fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6/_history/2

Error Handling

Common HTTP status codes:

Error Response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "required",
      "details": {
        "text": "Patient.name: At least one name is required"
      }
    }
  ]
}

Validation

Before saving, validate a resource against the FHIR profile. The platform exposes a single $validate operation that accepts any resource type:

curl -X POST https://api.esus.health/fhir/\$validate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{ "resourceType": "Patient", "name": [ { "family": "Smith" } ] }'

The response is an OperationOutcome describing any validation issues without persisting the resource.

Congratulations

You’ve completed the Getting Started guide! Take the quiz to earn your Level 1 certification.