# Patient Demographics Query (PDQ)
URL: https://docs.awellhealth.com/docs/connect-systems/patient-demographics-query

> For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt).



**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 [#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.

## Trigger event [#trigger-event]

A clinician in Awell Care asks to import a patient, supplying the identifier to search on.

## Request [#request]

The request is a [parameterized search](https://profiles.ihe.net/ITI/PDQm/ITI-78.html) from Awell to
the supplier.

**Awell currently searches on the `identifier` parameter only.** The coding **system** and **code** used
for the search are configured in the integration settings in the Awell app.

### GET [#get]

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

### POST [#post]

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

## Response [#response]

### Patient record fields [#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 [#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 [#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 [#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 [#next-steps]

* [Patient identifiers](/docs/connect-systems/patient-identifiers) for how the search key is defined.
* [Create patients](/docs/run-care-flows/create-patients) for what happens after the prefill.