# Patients URL: https://docs.awellhealth.com/api-reference/reference/patients > For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt). Patients are the people receiving care in Awell. Use these operations to create and update patients, look them up by Awell ID or by a business identifier, and read or write their data points. Pick the retrieval operation based on the identifier you hold: | Operation | When to use | | --------------------------------------------- | ----------------------------------------------------------- | | [`patient`](#patient) | You have the Awell patient ID. | | [`patientByIdentifier`](#patientbyidentifier) | You have a business identifier (a `system` + `value` pair). | A **business identifier** is a `system` + `value` pair, following the FHIR identifier model. The `system` is a namespace, given as an absolute URL so the pair is globally unique. The `value` is the identifier within that namespace. One patient can hold several: an MRN from one system, a payer ID from another. For the full treatment, see [patient identifiers](https://developers.awellhealth.com/awell-orchestration/docs/misc/patient-identifiers) on the developer hub. ## Queries [#queries] ### `patient` [#patient] Retrieves a single patient by their Awell ID. **Arguments** | Argument | Type | Required | Description | | -------- | --------- | -------- | --------------------------- | | `id` | `String!` | Yes | The Awell ID of the patient | **Returns:** `PatientPayload!` **Example** ```graphql query Patient($id: String!) { patient(id: $id) { code patient { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } success } } ``` Variables: ```json { "id": "" } ``` ### `patientByIdentifier` [#patientbyidentifier] Retrieves a single patient by a business identifier (a system and value pair). **Arguments** | Argument | Type | Required | Description | | -------- | --------- | -------- | --------------------- | | `system` | `String!` | Yes | The identifier system | | `value` | `String!` | Yes | The identifier value | **Returns:** `PatientPayload!` **Example** ```graphql query PatientByIdentifier($system: String!, $value: String!) { patientByIdentifier(system: $system, value: $value) { code patient { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } success } } ``` Variables: ```json { "system": "", "value": "" } ``` ### `patientDataPointHistory` [#patientdatapointhistory] Full change history (newest first) of one of a patient's data points, with every value audited. **Arguments** | Argument | Type | Required | Description | | -------------------------- | --------- | -------- | ----------------------------------- | | `data_point_definition_id` | `String!` | Yes | The ID of the data point definition | | `patient_id` | `String!` | Yes | The ID of the patient | **Returns:** `[PatientDataPointGraphqlType!]!` **Example** ```graphql query PatientDataPointHistory($data_point_definition_id: String!, $patient_id: String!) { patientDataPointHistory(data_point_definition_id: $data_point_definition_id, patient_id: $patient_id) { activity_id data_point_definition_id data_set_id data_source_id date id key label provenance { activity_id actor actor_email actor_name careflow_id collected_at ingestion_id method step_id track_id } serialized_value status valueType } } ``` Variables: ```json { "data_point_definition_id": "", "patient_id": "" } ``` ### `patientDataPoints` [#patientdatapoints] Latest value per data point for a patient, as shown in the data viewer's list. **Arguments** | Argument | Type | Required | Description | | ------------ | --------- | -------- | --------------------- | | `patient_id` | `String!` | Yes | The ID of the patient | **Returns:** `[PatientDataPointGraphqlType!]!` **Example** ```graphql query PatientDataPoints($patient_id: String!) { patientDataPoints(patient_id: $patient_id) { activity_id data_point_definition_id data_set_id data_source_id date id key label provenance { activity_id actor actor_email actor_name careflow_id collected_at ingestion_id method step_id track_id } serialized_value status valueType } } ``` Variables: ```json { "patient_id": "" } ``` ### `patientDemographicsQueryConfiguration` [#patientdemographicsqueryconfiguration] Returns the configuration for querying patient demographics. **Returns:** `PatientDemographicsQueryConfigurationPayload!` **Example** ```graphql query PatientDemographicsQueryConfiguration { patientDemographicsQueryConfiguration { input_box_text is_enabled } } ``` ### `patientPathways` [#patientpathways] Lists the care flows for a patient. **Arguments** | Argument | Type | Required | Description | | -------------------- | ----------------------- | -------- | --------------------------------------------------------------- | | `filters` | `FilterPatientPathways` | No | Filters to narrow the results | | `patient_id` | `String` | No | The ID of the patient | | `patient_identifier` | `IdentifierInput` | No | A business identifier for the patient (a system and value pair) | **Returns:** `PatientPathwaysPayload!` **Example** ```graphql query PatientPathways($filters: FilterPatientPathways, $patient_id: String, $patient_identifier: IdentifierInput) { patientPathways(filters: $filters, patient_id: $patient_id, patient_identifier: $patient_identifier) { code patientPathways { active_activities archived_date baseline_info { value } complete_date created { date user_email user_id user_name } failed_activities id is_archived latest_activity_date latest_activity_title latest_activity_type pathway_definition_id release_id start_date status status_explanation stop_date title total_activities version } success } } ``` Variables: ```json { "filters": { "status": {} }, "patient_id": "", "patient_identifier": { "system": "", "value": "" } } ``` ### `patients` [#patients] Lists patients, with optional filtering, pagination, and sorting. **Arguments** | Argument | Type | Required | Description | | ------------ | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------ | | `filters` | `FilterPatients` | No | Filters to narrow the results | | `pagination` | `PaginationParams` | No | How many results to return and the offset to start from — see [Pagination](/api-reference/guides/pagination) | | `sorting` | `SortingParams` | No | The field to sort by and the sort direction — see [Pagination](/api-reference/guides/pagination) | **Returns:** `PatientsPayload!` **Example** ```graphql query Patients($filters: FilterPatients, $pagination: PaginationParams, $sorting: SortingParams) { patients(filters: $filters, pagination: $pagination, sorting: $sorting) { code pagination { count offset total_count } patients { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } sorting { direction field } success } } ``` Variables: ```json { "filters": {}, "pagination": { "count": 0, "offset": 0 }, "sorting": { "direction": "", "field": "" } } ``` ### `searchPatientsByNationalRegistryNumber` [#searchpatientsbynationalregistrynumber] Searches for patients by national registry number. **Arguments** | Argument | Type | Required | Description | | -------------------------- | --------- | -------- | -------------------------------------- | | `national_registry_number` | `String!` | Yes | The patient's national registry number | **Returns:** `SearchPatientsPayload!` **Example** ```graphql query SearchPatientsByNationalRegistryNumber($national_registry_number: String!) { searchPatientsByNationalRegistryNumber(national_registry_number: $national_registry_number) { code patients { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } success } } ``` Variables: ```json { "national_registry_number": "" } ``` ### `searchPatientsByPatientCode` [#searchpatientsbypatientcode] Searches for patients by patient code. **Arguments** | Argument | Type | Required | Description | | -------------- | --------- | -------- | ---------------- | | `patient_code` | `String!` | Yes | The patient code | **Returns:** `SearchPatientsPayload!` **Example** ```graphql query SearchPatientsByPatientCode($patient_code: String!) { searchPatientsByPatientCode(patient_code: $patient_code) { code patients { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } success } } ``` Variables: ```json { "patient_code": "" } ``` ## Mutations [#mutations] ### `addIdentifierToPatient` [#addidentifiertopatient] Adds a business identifier to a patient. **Arguments** | Argument | Type | Required | Description | | -------- | ------------------------------ | -------- | -------------------------------------------------- | | `input` | `AddIdentifierToPatientInput!` | Yes | The identifier to add and the patient to add it to | **Returns:** `AddIdentifierToPatientPayload!` **Example** ```graphql mutation AddIdentifierToPatient($input: AddIdentifierToPatientInput!) { addIdentifierToPatient(input: $input) { code patient { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } success } } ``` Variables: ```json { "input": { "identifier": { "system": "", "value": "" }, "patient_id": "" } } ``` ### `clearPatientData` [#clearpatientdata] Clear patient data-point values by stable id: appends a null "no value" version per profile field (restorable from history); removes the patient’s value for an identifier system. **Arguments** | Argument | Type | Required | Description | | -------- | ------------------------ | -------- | ------------------------------------------ | | `input` | `ClearPatientDataInput!` | Yes | The details of which patient data to clear | **Returns:** `[PatientDataPointGraphqlType!]!` **Example** ```graphql mutation ClearPatientData($input: ClearPatientDataInput!) { clearPatientData(input: $input) { activity_id data_point_definition_id data_set_id data_source_id date id key label provenance { activity_id actor actor_email actor_name careflow_id collected_at ingestion_id method step_id track_id } serialized_value status valueType } } ``` Variables: ```json { "input": { "keys": [ "" ], "patient_id": "" } } ``` ### `createPatient` [#createpatient] Creates a patient. **Arguments** | Argument | Type | Required | Description | | -------- | -------------------- | -------- | ------------------------------------ | | `input` | `CreatePatientInput` | No | The details of the patient to create | **Returns:** `CreatePatientPayload!` **Example** ```graphql mutation CreatePatient($input: CreatePatientInput) { createPatient(input: $input) { code patient { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } success } } ``` Variables: ```json { "input": {} } ``` ### `deletePatient` [#deletepatient] Deletes a patient. **Arguments** | Argument | Type | Required | Description | | -------- | --------------------- | -------- | ------------------------------------ | | `input` | `DeletePatientInput!` | Yes | The details of the patient to delete | **Returns:** `EmptyPayload!` **Example** ```graphql mutation DeletePatient($input: DeletePatientInput!) { deletePatient(input: $input) { code success } } ``` Variables: ```json { "input": {} } ``` ### `mergePatients` [#mergepatients] Merges two patients into one, transferring the deleted patient's care flows to the patient that is kept. **Arguments** | Argument | Type | Required | Description | | -------- | --------------------- | -------- | --------------------------------------------- | | `input` | `MergePatientsInput!` | Yes | The patient to keep and the patient to delete | **Returns:** `MergePatientsPayload!` **Example** ```graphql mutation MergePatients($input: MergePatientsInput!) { mergePatients(input: $input) { code deleted_patient_id success transferred_careflow_ids transferred_count } } ``` Variables: ```json { "input": { "patient_id_to_delete": "", "patient_id_to_keep": "" } } ``` ### `requestPatientDemographics` [#requestpatientdemographics] Retrieve patient demographics from an external system **Arguments** | Argument | Type | Required | Description | | -------- | --------------------------- | -------- | --------------------------------------- | | `input` | `PatientDemographicsInput!` | Yes | The details of the demographics request | **Returns:** `PatientDemographicsPayload!` **Example** ```graphql mutation RequestPatientDemographics($input: PatientDemographicsInput!) { requestPatientDemographics(input: $input) { code entry { address { city country state street zip } birth_date email first_name identifier { system value } last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } query_id status success total } } ``` Variables: ```json { "input": { "patient_identifier": "" } } ``` ### `setPatientDataPointValue` [#setpatientdatapointvalue] Manually set a patient data-point value, the operation behind the patient data viewer's Save/Restore. **Arguments** | Argument | Type | Required | Description | | -------- | -------------------------------- | -------- | --------------------------- | | `input` | `SetPatientDataPointValueInput!` | Yes | The data point value to set | **Returns:** `PatientDataPointGraphqlType` **Example** ```graphql mutation SetPatientDataPointValue($input: SetPatientDataPointValueInput!) { setPatientDataPointValue(input: $input) { activity_id data_point_definition_id data_set_id data_source_id date id key label provenance { activity_id actor actor_email actor_name careflow_id collected_at ingestion_id method step_id track_id } serialized_value status valueType } } ``` Variables: ```json { "input": { "data_point_definition_id": "", "patient_id": "", "valueType": "ATTACHMENT" } } ``` ### `updatePatient` [#updatepatient] Updates a patient's profile. **Arguments** | Argument | Type | Required | Description | | -------- | --------------------- | -------- | ------------------------------------ | | `input` | `UpdatePatientInput!` | Yes | The details of the patient to update | **Returns:** `UpdatePatientPayload!` **Example** ```graphql mutation UpdatePatient($input: UpdatePatientInput!) { updatePatient(input: $input) { code patient { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } success } } ``` Variables: ```json { "input": { "patient_id": "", "profile": {} } } ``` ### `updatePatientData` [#updatepatientdata] Write patient-profile data-point VALUES (profile fields + identifier values) to the patient-data store. Values only. **Arguments** | Argument | Type | Required | Description | | -------- | ------------------------- | -------- | -------------------------- | | `input` | `UpdatePatientDataInput!` | Yes | The patient data to update | **Returns:** `[PatientDataPointGraphqlType!]!` **Example** ```graphql mutation UpdatePatientData($input: UpdatePatientDataInput!) { updatePatientData(input: $input) { activity_id data_point_definition_id data_set_id data_source_id date id key label provenance { activity_id actor actor_email actor_name careflow_id collected_at ingestion_id method step_id track_id } serialized_value status valueType } } ``` Variables: ```json { "input": { "patient_id": "" } } ``` ### `updatePatientDemographicsQuery` [#updatepatientdemographicsquery] Update which patient was created after import request for logging purposes **Arguments** | Argument | Type | Required | Description | | -------- | -------------------------------------- | -------- | ----------------------------------------------- | | `input` | `UpdatePatientDemographicsQueryInput!` | Yes | The details of the demographics query to update | **Returns:** `UpdatePatientDemographicsQueryPayload!` **Example** ```graphql mutation UpdatePatientDemographicsQuery($input: UpdatePatientDemographicsQueryInput!) { updatePatientDemographicsQuery(input: $input) { code created_patient_entry_index created_patient_id success } } ``` Variables: ```json { "input": { "created_patient_entry_index": 0, "created_patient_id": "", "query_id": "" } } ``` ### `updatePatientLanguage` [#updatepatientlanguage] Updates a patient's preferred language. **Arguments** | Argument | Type | Required | Description | | -------- | ----------------------------- | -------- | ----------------------------------------- | | `input` | `UpdatePatientLanguageInput!` | Yes | The patient and preferred language to set | **Returns:** `UpdatePatientLanguagePayload!` **Example** ```graphql mutation UpdatePatientLanguage($input: UpdatePatientLanguageInput!) { updatePatientLanguage(input: $input) { code success user { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } } } ``` Variables: ```json { "input": { "preferred_language": "" } } ``` ### `upsertPatient` [#upsertpatient] Creates a patient, or updates the existing patient matching the identifier. **Arguments** | Argument | Type | Required | Description | | -------- | --------------------- | -------- | ---------------------------------------------- | | `input` | `UpsertPatientInput!` | Yes | The details of the patient to create or update | **Returns:** `UpsertPatientPayload!` **Example** ```graphql mutation UpsertPatient($input: UpsertPatientInput!) { upsertPatient(input: $input) { code patient { id profile { birth_date email first_name last_name mobile_phone name national_registry_number patient_code patient_timezone phone preferred_language sex } tenant_id } success } } ``` Variables: ```json { "input": { "patient_identifier": { "system": "", "value": "" } } } ```