Oystehr Services
eRx
Patient Sync
🚧

The eRx Service is currently in beta.

Patient Sync

Patient information stored in the FHIR Service can be synced to the eRx service. This makes the patient's information available to the prescriber when they are prescribing medications.

Access Policy

To sync patients, your user needs to have the following minimum access policy:

{
  "rule": [
    {
      "action": "eRx:SyncPatient",
      "resource": "eRx:Patient",
      "effect": "Allow"
    },
    {
      "resource": "FHIR:Patient:your_patient_uuid",
      "action": ["FHIR:Read"],
      "effect": "Allow"
    },
    {
      "resource": "FHIR:Patient:your_patient_uuid",
      "action": ["FHIR:Update"],
      "effect": "Allow"
    },
    {
      "resource": "FHIR:AllergyIntolerance:*",
      "action": ["FHIR:Read"],
      "effect": "Allow",
      "condition": "patient:Patient._id=your_patient_uuid"
    },
    {
      "resource": "FHIR:AllergyIntolerance:*",
      "action": ["FHIR:Search"],
      "effect": "Allow"
    },
    {
      "resource": "FHIR:MedicationStatement:*",
      "action": ["FHIR:Read"],
      "effect": "Allow",
      "condition": "subject:Patient._id=your_patient_uuid"
    },
    {
      "resource": "FHIR:MedicationStatement:*",
      "action": ["FHIR:Search"],
      "effect": "Allow"
    }
  ]
}

Data that is Synced

The following patient information is sent to Photon:

  • name (first and last)
  • date of birth
  • gender
  • email
  • phone number
  • address
  • allergies
  • medication history

How to Sync

When you trigger a patient sync (opens in a new tab), information is collected from the referenced FHIR Patient record and sent to Photon. The required fields for patient sync are:

  • name (first and last)
  • date of birth
  • gender
  • phone number

Here is an example of a patient creation followed by a sync:

create-patient.ts
import Oystehr from '@oystehr/sdk';
import { Patient } from 'fhir/r4b';
 
const patient: Patient = {
  resourceType: 'Patient',
  name: [
    {
      family: 'Shaw',
      given: ['Amy', 'V.'],
    },
  ],
  telecom: [
    {
      system: 'phone',
      value: '+14231112222',
      use: 'home',
      extension: [
        {
          url: 'https://extensions.fhir.oystehr.com/contact-point/telecom-phone-erx',
        },
      ],          
    },
    {
      system: 'email',
      value: '[email protected]',
    },
  ],
  gender: 'female',
  birthDate: '1987-02-20',
  address: [
    {
      line: ['49 Meadow St', 'Apt 2'],
      city: 'Mounds',
      state: 'OK',
      postalCode: '74047',
      country: 'US',
    },
  ],
};
 
const oystehr = new Oystehr({ accessToken: '<your_access_token>' });
const createdResource = await oystehr.fhir.create<Patient>(patient);
const syncPatientResult = await oystehr.erx.syncPatient({ patientId: createdResource.id });

When synchronizing patient phone numbers for eRx purposes, phone numbers with extension URL of https://extensions.fhir.oystehr.com/contact-point/telecom-phone-erx will be preferenced. Phone number search is conducted in the following order:

  1. Patient Resource, telecom tagged for eRx
  2. Patient Resource's contacts, telecoms tagged for eRx
  3. Patient Resource, telecom, untagged
  4. Patient Resource's contacts, untagged

Phone Number Validation

While FHIR supports placing any phone number in the patient's telecom field, the eRx service is more selective. Phone numbers are validated with AWS (opens in a new tab), and patient sync will return a validation error if the phone number cannot be real. For example, the 999 area code is unassigned so a number with this area code would cause a sync failure. Because this specific error can be easily encountered, we recommend handling it.

{
  "statusCode": 400,
  "body": {
    "message": "Patient property was invalid: phone",
    "code": "4006"
  }
}

Photon Patient ID

When a patient is synced, a unique patient ID is generated by Photon and returned. This ID is then stored in the FHIR Patient on an identifier and used to identify the patient in future requests. Here is an example:

{
  "identifier": [
    {
      "use":"official",
      "value":"pat_01HR3FBJFIWLGBP22JWQFK8WX9",
      "system":"http://api.zapehr.com/photon-patient-id"
    }
  ]
}

Patient Allergies

When you create an allergy (opens in a new tab) in the FHIR service that is associated with a patient, this information is sent to Photon during patient sync. Here is an example of an allergy creation:

create-allergy.ts
import Oystehr from '@oystehr/sdk';
import { AllergyIntolerance } from 'fhir/r4b';
 
const allergy: AllergyIntolerance = {
  resourceType: 'AllergyIntolerance',
  patient: {
    reference: `Patient/${your-fhir-patient-id}`,
  },
  code: {
    coding: [
      {
        system: 'http://api.zapehr.com/photon-allergy-id',
        code: 'alg_01GBAPSGG6X7NJ8DV6VF1SFGTQ',
        display: 'peanut allergenic extract',
      }
    ],
  },
  onsetDateTime: '2021-08-01',
  note: [
    {
      text: 'Patient has had allergy since 10 yo.',
    },
  ],
};
 
const oystehr = new Oystehr({ accessToken: '<your_access_token>' });
const createdResource = await oystehr.fhir.create<AllergyIntolerance>(allergy);

The following allergy information is synced:

  • allergen id
  • onset date
  • comment

Of these, only the allergen id is required. The other fields are optional.

Photon Allergen ID

Each allergen within Photon's system has a unique identifier used to track it, and this is the identifier than needs to be sent to Photon. Here is an example of an allergen identifier:

{
  "code": {
    "coding": [
      {
        "system": "http://api.zapehr.com/photon-allergy-id",
        "code": "alg_01GBAPSGG6X7NJ8DV6VF1SFGTQ",
        "display": "peanut allergenic extract"
      }
    ]
  }
}

The code system http://api.zapehr.com/photon-allergy-id is used to identify the allergy codings that should be synced to Photon. If a coding has a system other than this, it will be excluded from what is sent to Photon. Use the allergy search endpoint to find the allergen id for the allergen you wish to sync.

Medication History

When you create a medication statement (opens in a new tab) that is associated with a patient, this information is sent to Photon during patient sync. Here is an example of a medication creation:

create-medication.ts
import Oystehr from '@oystehr/sdk';
import { MedicationStatement } from 'fhir/r4b';
 
const medication: MedicationStatement = {
  resourceType: 'MedicationStatement',
  status: 'active',
  subject: {
    reference: `Patient/${your-fhir-patient-id}`,
  },
  medicationCodeableConcept: {
    coding: [
      {
        system: 'http://api.zapehr.com/photon-medication-id',
        code: 'med_01HNXFYCM6YP675JGEQX19VD17',
        display: 'Amoxil (Amoxicillin 400 mg /5mL) Oral powder, for suspension',
      }
    ],
  },
  note: [
    {
      text: 'Patient has been taking this medication since 10 yo.',
    },
  ],
};
 
const oystehr = new Oystehr({ accessToken: '<your_access_token>' });
const createdResource = await oystehr.fhir.create<MedicationStatement>(medication);

The following medication information is synced:

  • medication id
  • active status
  • comment

Of these, medication id and active status are required.

Photon Medication ID

Each medication within Photon's system has a unique identifier used to track it, and this is the identifier than needs to be sent to Photon. Here is an example of a medication identifier:

{
  "medicationCodeableConcept": {
    "coding": [
      {
        "system": "http://api.zapehr.com/photon-medication-id",
        "code": "med_01HNXFYCM6YP675JGEQX19VD17",
        "display": "Amoxil (Amoxicillin 400 mg /5mL) Oral powder, for suspension"
      }
    ]
  }
}

The code system http://api.zapehr.com/photon-medication-id is used to identify the medication codings that should be synced to Photon. If a coding has a system other than this, it will be excluded from what is sent to Photon. Use the medication search endpoint to find the medication id for the medication you wish to sync.

Create PrescriptionsAllergy Search