Awell Docs

Create, find, update, and manage patients and their data points in the Awell Orchestration API.

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`	You have the Awell patient ID.
`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 on the developer hub.

Queries

`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

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:

{
  "id": "<string>"
}

`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

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:

{
  "system": "<string>",
  "value": "<string>"
}

`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

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:

{
  "data_point_definition_id": "<string>",
  "patient_id": "<string>"
}

`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

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:

{
  "patient_id": "<string>"
}

`patientDemographicsQueryConfiguration`

Returns the configuration for querying patient demographics.

Returns: PatientDemographicsQueryConfigurationPayload!

Example

query PatientDemographicsQueryConfiguration {
  patientDemographicsQueryConfiguration {
    input_box_text
    is_enabled
  }
}

`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

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:

{
  "filters": {
    "status": {}
  },
  "patient_id": "<string>",
  "patient_identifier": {
    "system": "<string>",
    "value": "<string>"
  }
}

`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
`sorting`	`SortingParams`	No	The field to sort by and the sort direction — see Pagination

Returns: PatientsPayload!

Example

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:

{
  "filters": {},
  "pagination": {
    "count": 0,
    "offset": 0
  },
  "sorting": {
    "direction": "<string>",
    "field": "<string>"
  }
}

`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

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:

{
  "national_registry_number": "<string>"
}

`searchPatientsByPatientCode`

Searches for patients by patient code.

Arguments

Argument	Type	Required	Description
`patient_code`	`String!`	Yes	The patient code

Returns: SearchPatientsPayload!

Example

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:

{
  "patient_code": "<string>"
}

Mutations

`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

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:

{
  "input": {
    "identifier": {
      "system": "<string>",
      "value": "<string>"
    },
    "patient_id": "<string>"
  }
}

`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

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:

{
  "input": {
    "keys": [
      "<string>"
    ],
    "patient_id": "<string>"
  }
}

`createPatient`

Creates a patient.

Arguments

Argument	Type	Required	Description
`input`	`CreatePatientInput`	No	The details of the patient to create

Returns: CreatePatientPayload!

Example

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:

{
  "input": {}
}

`deletePatient`

Deletes a patient.

Arguments

Argument	Type	Required	Description
`input`	`DeletePatientInput!`	Yes	The details of the patient to delete

Returns: EmptyPayload!

Example

mutation DeletePatient($input: DeletePatientInput!) {
  deletePatient(input: $input) {
    code
    success
  }
}

Variables:

{
  "input": {}
}

`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

mutation MergePatients($input: MergePatientsInput!) {
  mergePatients(input: $input) {
    code
    deleted_patient_id
    success
    transferred_careflow_ids
    transferred_count
  }
}

Variables:

{
  "input": {
    "patient_id_to_delete": "<string>",
    "patient_id_to_keep": "<string>"
  }
}

`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

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:

{
  "input": {
    "patient_identifier": "<string>"
  }
}

`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

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:

{
  "input": {
    "data_point_definition_id": "<string>",
    "patient_id": "<string>",
    "valueType": "ATTACHMENT"
  }
}

`updatePatient`

Updates a patient's profile.

Arguments

Argument	Type	Required	Description
`input`	`UpdatePatientInput!`	Yes	The details of the patient to update

Returns: UpdatePatientPayload!

Example

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:

{
  "input": {
    "patient_id": "<string>",
    "profile": {}
  }
}

`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

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:

{
  "input": {
    "patient_id": "<string>"
  }
}

`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

mutation UpdatePatientDemographicsQuery($input: UpdatePatientDemographicsQueryInput!) {
  updatePatientDemographicsQuery(input: $input) {
    code
    created_patient_entry_index
    created_patient_id
    success
  }
}

Variables:

{
  "input": {
    "created_patient_entry_index": 0,
    "created_patient_id": "<string>",
    "query_id": "<string>"
  }
}

`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

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:

{
  "input": {
    "preferred_language": "<string>"
  }
}

`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

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:

{
  "input": {
    "patient_identifier": {
      "system": "<string>",
      "value": "<string>"
    }
  }
}

Patients

On this page