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

    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"
  }]
}