Patient

Patients are an essential part of Atticus. On this page, we'll dive into the different patient endpoints you can use to manage patients programmatically. We'll look at how to query, create, update, and delete patients.

The Patient model

The Patient model contains all the basic demographic information about a patient, including their name, birth date, gender and identifiers.

Properties

The Patient model conforms to the FHIR Patient resource. The following properties are available:

Name
resourceType*
Type
'Patient'
Description
The FHIR resource type. This must be set to 'Patient'.
Name
identifier
Type
Identifier[]
Description
An array of Identifier objects for this patient (e.g. MRN, SSN). This is the place to store EHR identifiers or hospital identifiers for the patient. The API only accepts the system and value fields (both required) on each identifier. Any other Identifier field (use, type, period, assigner) is rejected with a 422 validation error. More information about identifiers in Atticus can be found here.
Name
name
Type
HumanName[]
Description
The name of the patient. This includes given names and family name. Name contains an array of FHIR HumanName objects. Only the first entry in the array is stored; additional entries are discarded. Within a name, only prefix, given, family, and text are used; other HumanName fields (use, suffix, period) are silently ignored.
Name
birthDate
Type
date
Description
The patient's date of birth.
Name
gender
Type
code
Description
Administrative gender. Possible values are: - male - female - other - unknown

POST/Patient

Create a new Patient

This endpoint allows you to create a new Patient.

Creating a patient whose identifier already exists in the tenant returns 409 Conflict with issue code duplicate and a Location header pointing at the existing Patient.

Request

POST

/Patient

curl -X POST https://reports.tiro.health/fhir/r5/Patient \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "name": [{
      "given": ["John"],
      "family": "Smith"
    }],
    "birthDate": "1970-01-01",
    "gender": "male",
    "identifier": [{
      "system": "http://hospital.example.org/identifiers/mrn",
      "value": "12345"
    }]
  }'

Response

{
  "resourceType": "Patient",
  "id": "1",
  "name": [{
    "given": ["John"],
    "family": "Smith"
  }],
  "birthDate": "1970-01-01",
  "gender": "male",
  "identifier": [{
    "system": "http://hospital.example.org/identifiers/mrn",
    "value": "12345"
  }]
}

PUT/Patient?identifier=<system>|<value>

Conditionally update a Patient

This endpoint allows you to update a Patient by matching on specific criteria. The search criteria are provided as query parameters, and the updated Patient data is provided in the request body. The ?identifier= query parameter is required: a bare PUT /Patient without it returns a 422. When no Patient is found that matches the search criteria, a new Patient is created; the response status is still 200 OK (not 201).

Conditional PUT merges the submitted identifiers with the existing ones, whereas PUT /Patient/{id} replaces the identifier list.

Request

PUT

/Patient?identifier=http://hospital.example.org/identifiers/mrn|12345

curl -X PUT "https://reports.tiro.health/fhir/r5/Patient?identifier=http://hospital.example.org/identifiers/mrn|12345" \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "name": [{
      "given": ["John"],
      "family": "Smith"
    }],
    "birthDate": "1970-01-01",
    "gender": "male",
    "identifier": [{
      "system": "http://hospital.example.org/identifiers/mrn",
      "value": "12345"
    }]
  }'

Response

{
  "resourceType": "Patient",
  "id": "1",
  "name": [{
    "given": ["John"],
    "family": "Smith"
  }],
  "birthDate": "1970-01-01",
  "gender": "male",
  "identifier": [{
    "system": "http://hospital.example.org/identifiers/mrn",
    "value": "12345"
  }]
}

PUT/Patient/:id

Update a new Patient

This endpoint allows you to update an existing Patient by providing both the Patient id and the updated Patient data. This is a partial update: omitted fields are left unchanged. The identifier list, when provided, replaces the existing list.

Request

PUT

/Patient/1

curl -X PUT https://reports.tiro.health/fhir/r5/Patient/1 \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "id": "1",
    "name": [{
      "given": ["John"],
      "family": "Smith"
    }],
    "birthDate": "1970-01-01",
    "gender": "male",
    "identifier": [{
      "system": "http://hospital.example.org/identifiers/mrn",
      "value": "12345"
    }]
  }'

Response

{
  "resourceType": "Patient",
  "id": "1",
  "name": [{
    "given": ["John"],
    "family": "Smith"
  }],
  "birthDate": "1970-01-01",
  "gender": "male",
  "identifier": [{
    "system": "http://hospital.example.org/identifiers/mrn",
    "value": "12345"
  }]
}

GET/Patient/:id

Get an existing Patient

This endpoint allows you to retrieve an existing Patient by providing the Patient id.

Request

GET

/Patient/1

curl -G https://reports.tiro.health/fhir/r5/Patient/1 \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \

DELETE/Patient/:id

Delete an existing Patient

This endpoint allows you to delete an existing Patient by providing the Patient id. Once a Patient is deleted, it cannot be recovered. A successful delete returns 204 No Content with an empty body. If the patient is still referenced by other resources, the request returns 409 Conflict.

Request

DELETE

/Patient/1

curl -X DELETE https://reports.tiro.health/fhir/r5/Patient/1 \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \

Response

HTTP/1.1 204 No Content