Patient Demographics Query (PDQ)

The PDQ integration reference: how Awell searches a Patient Demographics Supplier by identifier, what the request and response look like, and how Awell Care reacts.

Patient Demographics Query (PDQ) lets a care team import a patient into Awell from an external system rather than typing their details in. Awell searches the external system by identifier and prefills the create-patient form with what comes back.

This page is the technical reference for that exchange.

Actors

Patient Demographics Consumer. Awell, which issues the search.
Patient Demographics Supplier. The external system, which answers it.

A supplier can act as a proxy, forwarding the query to the system that actually holds the records, which is how a hospital can expose a legacy system without changing it.

curl {endpoint}/Patient?identifier:of-type={system}|{code}|{value}

POST

curl {endpoint}/Patient/_search \
  -X POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'identifier:of-type={system}|{code}|{value}'

Response

Patient record fields

Field	Type	Description
`patient_code`	string	A value that uniquely identifies the patient in the supplier's system. Can be the identifier used for the search
`first_name`	string	First name of the patient
`last_name`	string	Last name of the patient
`birth_date`	string	Birth date as an ISO 8601 string
`email`	string	Email address of the patient
`phone`	string	Landline number as an E.164 string
`mobile_phone`	string	Mobile number as an E.164 string
`national_registry_number`	string	National registry number, for example the social security number in Belgium
`sex`	number	`0` not known, `1` male, `2` female
`address.street`	string	Street address
`address.city`	string	City
`address.zip`	string	ZIP or postal code
`address.state`	string	State
`address.country`	string	Country

HTTP status codes

200 OK is returned in both of these cases:

The supplier finds at least one patient record matching the search parameters.
The supplier finds none, sets total to 0, and returns no entry attributes.

A 200 response therefore does not mean a patient was found; read total to tell the two apart.

4XX means the request had bad syntax or could not be fulfilled. 5XX means the server failed to fulfill an apparently valid request.

Setup happens in the Awell app

The PDQ integration is enabled and configured under integration settings.

PDQ prefills the form, and the clinician always reviews

Awell processes the response and reports the outcome to the clinician in Awell Care:

Outcome	What the clinician sees
Request failed (4XX–5XX)	A message that the request failed, with the option to view request details
No results	A message that no patient record matched the search criteria
Exactly one result	The create-patient form, prefilled with the retrieved data, for review and editing before creating
More than one result	Each matching record, so the clinician can inspect and choose which to use

Next steps

Patient identifiers for how the search key is defined.
Create patients for what happens after the prefill.