Patient

A patient is a user that is receiving care.

The patient model

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the patient.

  • Name
    object
    Type
    string
    Description

    Always 'patient'.

  • Name
    mrn
    Type
    string
    Description

    Unique external identifier for the patient.

  • Name
    first_name
    Type
    string
    Description

    Patient's first name.

  • Name
    middle_name
    Type
    string
    Description

    Patient's middle name.

  • Name
    last_name
    Type
    string
    Description

    Patient's last name.

  • Name
    preferred_name
    Type
    string
    Description

    Patient's preferred name.

  • Name
    pronouns
    Type
    string
    Description

    Patient's pronouns.

  • Name
    sex
    Type
    string
    Description

    Patient's birth sex in SNOMED CT format. Options are:

    • "248153007" for Male
    • "248152002" for Female
    • "261665006" for Unknown
  • Name
    gender
    Type
    string
    Description

    Patient's gender. Can be 'Female,' 'Male,' or any custom entry.

  • Name
    sexual_orientation
    Type
    string
    Description

    Patient's sexual_orientation in SNOMED CT format. Options are

    • "20430005" for Heterosexual
    • "38628009" for Homosexual
    • "42035005" for Bisexual
    • "74964007" for Other
    • "261665006" for Unknown
    • "443390004" for Declined
  • Name
    email
    Type
    string
    Description

    Patient's email address.

  • Name
    phone
    Type
    string
    Description

    Patient's phone number.

  • Name
    date_of_birth
    Type
    string
    Description

    Patient's date of birth in ISO 8601 format.

  • Name
    ssn
    Type
    string
    Description

    Patient's SSN.

  • Name
    race
    Type
    array of strings
    Description

    Patient's races from the CDC's Race and Ethnicity Code Set.

  • Name
    ethnicity
    Type
    array of strings
    Description

    Patient's ethnicity from the CDC's Race and Ethnicity Code Set.

  • Name
    preferred_language
    Type
    string
    Description

    Patient's preferred language in the ISO 639-2 format.

  • Name
    caregiver
    Type
    string
    Description

    Patient's caregiver, if one exists.

  • Name
    caregiver_only
    Type
    boolean
    Description

    Whether the patient is only a caregiver in the system, not a patient receiving care themselves.

  • Name
    medical_centers
    Type
    array of strings
    Description

    Medical centers that the patient belongs to.

  • Name
    addresses
    Type
    array of objects
    Description
    Addresses of the patient.
  • Name
    timezone
    Type
    string
    Description

    Patient's timezone.

  • Name
    status_history
    Type
    array of objects
    Description
    Status history of the patient.
  • Name
    custom_data
    Type
    array of objects
    Description
    Custom field and values added to the patient object..
  • Name
    created_by
    Type
    string
    Description

    Creator of the patient.

  • Name
    created_at
    Type
    date-time
    Description

    Timestamp (in ISO 8601 format) of when the patient was created.

  • Name
    last_updated_at
    Type
    date-time
    Description

    Timestamp (in ISO 8601 format) of when the patient was last updated.

Response

{
    "id": "user_Z1zXZKvqrpwxbznuW6lJ",
    "object": "patient",
    "mrn": "8942726",

    "first_name": "Sally",
    "middle_name": "",
    "last_name": "Chen",
    "preferred_name": "Sal",
    "pronouns": "she/her",

    "sex": "248152002",
    "gender": "Female",
    "sexual_orientation": "20430005",

    "email": "sally@demo.com",
    "phone": "(408)872-5892",

    "date_of_birth": "1980-1-1",
    "ssn": "765876575",

    "race": ["2034-7"],
    "ethnicity": ["2186-5"],
    "preferred_language": "en",

    "caregiver": "user_X90XZKvqrpwxbznuW6lJ",
    "caregiver_only": false,
    "medical_centers": [
        "mctr_XbvBirnEb1Mli1OLwqnM"
    ],
    "addresses": [{
        "nickname": "Home",
        "line1": "60 W Main St",
        "city": "Avon",
        "state": "CT",
        "postal_code": "06001",
        "country": "US",
        "special_instructions": "Has a loud dog"
    }],
    "timezone": "America/New_York",
    "status_history": [{
        "status": "active",
        "changed_by": "user_Z1zXZKvqrpwxbznuW6lJ",
        "changed_at": 1653798303000
    }],
    "custom_data": [{
        "id": "cdta_ZR6ioEDFTnKLFn62okn",
        "key": "cfld_FZR6ioEDTkHKn62oknLF",
        "value": "Routine Care"
    }],
    "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
    "created_at": "2024-04-10T13:20:21.724Z",
    "last_updated_at": "2024-04-10T13:20:21.724Z"
}
POST/v2/patients

Create a patient

Creates a new patient.

Required attributes

  • Name
    first_name
    Type
    string
    Description

    Patient's first name.

  • Name
    last_name
    Type
    string
    Description

    Patient's last name.

  • Name
    gender
    Type
    string
    Description

    Required if using the prescriptions or labs integrations. Patient's gender. Can be 'Female,' 'Male,' or any custom entry.

  • Name
    email
    Type
    string
    Description

    Patient's email address.

  • Name
    phone
    Type
    string
    Description

    Required if using the prescriptions or labs integrations. Patient's phone number.

  • Name
    date_of_birth
    Type
    string
    Description

    Required if using the prescriptions or labs integrations. Patient's date of birth.

  • Name
    medical_centers
    Type
    array of strings
    Description

    Medical centers that the patient belongs to. Each patient must belong to at least one medical center.

  • Name
    addresses
    Type
    array of objects
    Description
    Required if using the prescriptions or labs integrations.Addresses of the patient.
  • Name
    timezone
    Type
    string
    Description

    Patient's timezone.

  • Name
    custom_data
    Type
    array of objects
    Description

    Custom field and values added to the patient object. Some fields may be required while others as optional.

Optional attributes

  • Name
    password
    Type
    string
    Description

    Sets the user's login password. If no value is provided, a password will be automatically generated.

  • Name
    mrn
    Type
    string
    Description

    Unique external identifier for the patient. If no value is provided, a unique MRN will be automatically generated.

  • Name
    middle_name
    Type
    string
    Description

    Patient's middle name.

  • Name
    preferred_name
    Type
    string
    Description

    Patient's preferred name.

  • Name
    pronouns
    Type
    string
    Description

    Patient's pronouns.

  • Name
    sex
    Type
    string
    Description

    Patient's birth sex in SNOMED CT format. Options are:

    • "248153007" for Male
    • "248152002" for Female
    • "261665006" for Unknown
  • Name
    sexual_orientation
    Type
    string
    Description

    Patient's sexual_orientation in SNOMED CT format. Options are

    • "20430005" for Heterosexual
    • "38628009" for Homosexual
    • "42035005" for Bisexual
    • "74964007" for Other
    • "261665006" for Unknown
    • "443390004" for Declined
  • Name
    ssn
    Type
    string
    Description

    Patient's SSN.

  • Name
    caregiver
    Type
    string
    Description

    Patient's caregiver, if one exists.

  • Name
    caregiver_only
    Type
    boolean
    Description

    If the patient is only a caregiver in the system, not a patient receiving care themselves.

  • Name
    status
    Type
    string
    Description

    Status of the patient. By default, this is set to 'active'.

    Possible values:
    prospective
    pending
    active
    discharged
  • Name
    care_team_members
    Type
    array of strings
    Description

    A list of organization members that are part of the patient's care team.

Response

{
    "id": "user_Z1zXZKvqrpwxbznuW6lJ",
    "object": "patient",
    "mrn": "8942726",

    "first_name": "Sally",
    "middle_name": "",
    "last_name": "Chen",
    "preferred_name": "Sal",
    "pronouns": "she/her",

    "sex": "248152002",
    "gender": "Female",
    "sexual_orientation": "20430005",

    "email": "sally@demo.com",
    "phone": "(408)872-5892",

    "date_of_birth": "1980-1-1",
    "ssn": "765876575",

    "race": ["2034-7"],
    "ethnicity": ["2186-5"],
    "preferred_language": "en",

    "caregiver": "user_X90XZKvqrpwxbznuW6lJ",
    "caregiver_only": false,
    "medical_centers": [
        "mctr_XbvBirnEb1Mli1OLwqnM"
    ],
    "addresses": [{
        "nickname": "Home",
        "line1": "60 W Main St",
        "city": "Avon",
        "state": "CT",
        "postal_code": "06001",
        "country": "US",
        "special_instructions": "Has a loud dog"
    }],
    "timezone": "America/New_York",
    "status_history": [{
        "status": "active",
        "changed_by": "user_Z1zXZKvqrpwxbznuW6lJ",
        "changed_at": 1653798303000
    }],
    "custom_data": [{
        "id": "cdta_ZR6ioEDFTnKLFn62okn",
        "key": "cfld_FZR6ioEDTkHKn62oknLF",
        "value": "Routine Care"
    }],
    "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
    "created_at": "2024-04-10T13:20:21.724Z",
    "last_updated_at": "2024-04-10T13:20:21.724Z"
}
GET/v2/patients/:id

Retrieve a patient

Retrieves the specified patient.

Response

{
   "id": "user_Z1zXZKvqrpwxbznuW6lJ",
   "object": "patient",
   "mrn": "8942726",

   "first_name": "Sally",
   "middle_name": "",
   "last_name": "Chen",
   "preferred_name": "Sal",
   "pronouns": "she/her",

   "sex": "248152002",
   "gender": "Female",
   "sexual_orientation": "20430005",

   "email": "sally@demo.com",
   "phone": "(408)872-5892",

   "date_of_birth": "1980-1-1",
   "ssn": "765876575",

   "race": ["2034-7"],
   "ethnicity": ["2186-5"],
   "preferred_language": "en",

   "caregiver": "user_X90XZKvqrpwxbznuW6lJ",
   "caregiver_only": false,
   "medical_centers": [
       "mctr_XbvBirnEb1Mli1OLwqnM"
   ],
   "addresses": [{
       "nickname": "Home",
       "line1": "60 W Main St",
       "city": "Avon",
       "state": "CT",
       "postal_code": "06001",
       "country": "US",
       "special_instructions": "Has a loud dog"
   }],
   "timezone": "America/New_York",
   "status_history": [{
       "status": "active",
       "changed_by": "user_Z1zXZKvqrpwxbznuW6lJ",
       "changed_at": 1653798303000
   }],
   "custom_data": [{
       "id": "cdta_ZR6ioEDFTnKLFn62okn",
       "key": "cfld_FZR6ioEDTkHKn62oknLF",
       "value": "Routine Care"
   }],
   "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
   "created_at": "2024-04-10T13:20:21.724Z",
   "last_updated_at": "2024-04-10T13:20:21.724Z"
}
POST/v2/patients/:id

Update a patient

Updates the specified patient object by setting the values of the parameters passed. Any other parameters not provided will not be modified.

Required attributes

    Optional attributes

    • Name
      first_name
      Type
      string
      Description

      Patient's first name.

    • Name
      middle_name
      Type
      string
      Description

      Patient's middle name.

    • Name
      last_name
      Type
      string
      Description

      Patient's last name.

    • Name
      preferred_name
      Type
      string
      Description

      Patient's preferred name.

    • Name
      pronouns
      Type
      string
      Description

      Patient's pronouns.

    • Name
      sex
      Type
      string
      Description

      Patient's birth sex in SNOMED CT format. Options are:

      • "248153007" for Male
      • "248152002" for Female
      • "261665006" for Unknown
    • Name
      gender
      Type
      string
      Description

      Patient's gender. Can be 'Female,' 'Male,' or any custom entry.

    • Name
      sexual_orientation
      Type
      string
      Description

      Patient's sexual_orientation in SNOMED CT format. Options are

      • "20430005" for Heterosexual
      • "38628009" for Homosexual
      • "42035005" for Bisexual
      • "74964007" for Other
      • "261665006" for Unknown
      • "443390004" for Declined
    • Name
      email
      Type
      string
      Description

      Patient's email address.

    • Name
      phone
      Type
      string
      Description

      Patient's phone number.

    • Name
      date_of_birth
      Type
      string
      Description

      Patient's date of birth in ISO 8601 format.

    • Name
      ssn
      Type
      string
      Description

      Patient's SSN.

    • Name
      race
      Type
      array of strings
      Description

      Patient's races from the CDC's Race and Ethnicity Code Set.

    • Name
      ethnicity
      Type
      array of strings
      Description

      Patient's ethnicity from the CDC's Race and Ethnicity Code Set.

    • Name
      preferred_language
      Type
      string
      Description

      Patient's preferred language in the ISO 639-2 format.

    • Name
      caregiver
      Type
      string
      Description

      Patient's caregiver, if one exists.

    • Name
      caregiver_only
      Type
      boolean
      Description

      Whether the patient is only a caregiver in the system, not a patient receiving care themselves.

    • Name
      medical_centers
      Type
      array of strings
      Description

      Medical centers that the patient belongs to.

    • Name
      addresses
      Type
      array of objects
      Description
      Addresses of the patient.
    • Name
      timezone
      Type
      string
      Description

      Patient's timezone.

    • Name
      status_history
      Type
      array of objects
      Description
      Status history of the patient.
    • Name
      custom_data
      Type
      array of objects
      Description
      Custom field and values added to the patient object..

    Response

    {
    "id": "user_Z1zXZKvqrpwxbznuW6lJ",
    "object": "patient",
    "mrn": "8942726",

    "first_name": "Sally",
    "middle_name": "",
    "last_name": "Chen",
    "preferred_name": "Sal",
    "pronouns": "she/her",

    "sex": "248152002",
    "gender": "Female",
    "sexual_orientation": "20430005",

    "email": "sally@demo.com",
    "phone": "(408)872-5892",

    "date_of_birth": "1980-1-1",
    "ssn": "765876575",

    "race": ["2034-7"],
    "ethnicity": ["2186-5"],
    "preferred_language": "en",

    "caregiver": "user_X90XZKvqrpwxbznuW6lJ",
    "caregiver_only": false,
    "medical_centers": [
        "mctr_XbvBirnEb1Mli1OLwqnM"
    ],
    "addresses": [{
        "nickname": "Home",
        "line1": "60 W Main St",
        "city": "Avon",
        "state": "CT",
        "postal_code": "06001",
        "country": "US",
        "special_instructions": "Has a loud dog"
    }],
    "timezone": "America/New_York",
    "status_history": [{
        "status": "active",
        "changed_by": "user_Z1zXZKvqrpwxbznuW6lJ",
        "changed_at": 1653798303000
    }],
    "custom_data": [{
        "id": "cdta_ZR6ioEDFTnKLFn62okn",
        "key": "cfld_FZR6ioEDTkHKn62oknLF",
        "value": "Routine Care"
    }],
    "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
    "created_at": "2024-04-10T13:20:21.724Z",
    "last_updated_at": "2024-04-10T13:20:21.724Z"
}
    GET/v2/patients/:id/ccda

    Generate a summary record

    Returns a summary record for the patient in the form of a Continuity of Care Document (CCDA).

    Optional query parameters

    • Name
      search_from
      Type
      date-time
      Description

      Date (in ISO 8601 format) from which to filter the summary record. Only records that are pertinent to the patient after this date will be included (e,g, an allergy was active after this date).

    • Name
      search_until
      Type
      date-time
      Description

      Date (in ISO 8601 format) until which to filter the summary record. Only records that are pertinent to the patient before this date will be included (e,g, an allergy was active before this date).

    • Name
      search_on
      Type
      date-time
      Description

      Date (in ISO 8601 format) on which to filter the summary record. Only records that are pertinent to the patient on this date will be included (e,g, an allergy was active on this date). Can either use search_on or search_from and search_until but not both.

    Request

    GET
    /v2/patients/:id/ccda
    curl https://{{base_subdomain}}.avonhealth.com/v2/patients?search_from=2020-12-31T00:00:00.000Z&search_until=2025-12-31T00:00:00.000Z \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}"

    Response

    {
  <?xml version="1.0" encoding="utf-8"?>
  <ClinicalDocument xmlns="urn:hl7-org:v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="C:\XML\CDA_SDTC_Schema\infrastructure\cda\CDA_SDTC.xsd" xmlns:voc="urn:hl7-org:v3/voc" xmlns:sdtc="urn:hl7-org:sdtc">
    <realmCode code="US"/>
    <typeId extension="POCD_HD000040" root="2.16.840.1.113883.1.3"/>
    <templateId root="2.16.840.1.113883.10.20.22.1.1" extension="2015-08-01"/>
    <templateId root="2.16.840.1.113883.10.20.22.1.1"/>
    <templateId root="2.16.840.1.113883.10.20.22.1.2" extension="2015-08-01"/>
    <templateId root="2.16.840.1.113883.10.20.22.1.2"/>
    <id extension="TT662" root="2.16.840.1.113883.19.5.99999.1"/>
    <code code="34133-9" displayName="Summarization of Episode Note" codeSystem="2.16.840.1.113883.6.1" codeSystemName="LOINC"/>
    <title>Transition of Care Document</title>
    ...
}
    GET/v2/patients

    List all patients

    Returns a list of all patients. Pass attributes to filter the list of patients based on that criteria.

    Optional query parameters

    • Name
      mrn
      Type
      string
      Description

      MRN to filter by.

    • Name
      email
      Type
      string
      Description

      Email address to filter by.

    • Name
      medical_centers
      Type
      string
      Description

      Comma-separated list of medical center IDs to filter by.

    • Name
      status
      Type
      string
      Description

      Status to filter by.

    Request

    GET
    /v2/patients
    curl https://{{base_subdomain}}.avonhealth.com/v2/patients?mrn=8942726&email=sally%40demo.com&medical_centers=mctr_XbvBirnEb1Mli1OLwqnM&status=active \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}"

    Response

    {
  "object": "list",
  "data": [{
    "id": "user_Z1zXZKvqrpwxbznuW6lJ",
    "object": "patient",
    "mrn": "8942726",

    "first_name": "Sally",
    "middle_name": "",
    "last_name": "Chen",
    "preferred_name": "Sal",
    "pronouns": "she/her",

    "sex": "248152002",
    "gender": "Female",
    "sexual_orientation": "20430005",

    "email": "sally@demo.com",
    "phone": "(408)872-5892",

    "date_of_birth": "1980-1-1",
    "ssn": "765876575",

    "race": ["2034-7"],
    "ethnicity": ["2186-5"],
    "preferred_language": "en",

    "caregiver": "user_X90XZKvqrpwxbznuW6lJ",
    "caregiver_only": false,
    "medical_centers": [
        "mctr_XbvBirnEb1Mli1OLwqnM"
    ],
    "addresses": [{
        "nickname": "Home",
        "line1": "60 W Main St",
        "city": "Avon",
        "state": "CT",
        "postal_code": "06001",
        "country": "US",
        "special_instructions": "Has a loud dog"
    }],
    "timezone": "America/New_York",
    "status_history": [{
        "status": "active",
        "changed_by": "user_Z1zXZKvqrpwxbznuW6lJ",
        "changed_at": 1653798303000
    }],
    "custom_data": [{
        "id": "cdta_ZR6ioEDFTnKLFn62okn",
        "key": "cfld_FZR6ioEDTkHKn62oknLF",
        "value": "Routine Care"
    }],
    "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
    "created_at": "2024-04-10T13:20:21.724Z",
    "last_updated_at": "2024-04-10T13:20:21.724Z"
  }]
}