Find Changes - Full

There are two different ways to get Changes from Greenlight

1. Changes Since
   1. This is a global (all Record Requests) way to find out what's new since the last time you checked. You don't need to check, patient-by-patient or request-by-request - you just call this endpoint to see anything that's been updated since your last check. This check is limited to the last 30 days, but the correct way to use this is to check once a day, once an hour, once every 15 minutes - whatever makes sense for your implementation.
2. Changes by Request
   1. This is a single Record Request call for up to a year at a time, to get all data and documents Greenlight retrieved. Some customers use Changes Since (above) to track Status changes and to pick up first retrievals of data... Then they ignore subsequent data retrievals for those Record Requests until months later, when a trial is finished, or treatment is completed, or a disability period is over. Only then do they want all the data/documents which Greenlight has continued to pick up.

Changes Since

The Find changes since timestamp endpoint will return any Record Request which has a new patient document associated with it OR has been cancelled.

• If Greenlight has retrieved a new document (CCD) or FHIR data since the time you indicated, the response will contain the data you need to download that document/data. See Fetch Document.

• If Greenlight has changed the status of a Record Request since the time you indicated, the response will contain the requestStatus, externalOrderId orderId, and requestId, so you can take the appropriate action. Greenlight will cancel the Record Request if the patient refused to give access, if the patient couldn't give us their correct portal credentials, if there is no portal, or if the portal is not one supported by Greenlight.

The Changes service responds with the time it "ended" (nextStartingTimestamp) - this is the time you should store and use the next time you call (startingTimestamp), to get all changes since then. This allows your system to detect every new document or data that is available or any Record Request cancellations.

The result of the Find changes since timestamp endpoint will look something like:

{
  "nextStartingTimestamp": "2022-11-22T15:47:41Z",
  "results": [
    {
      "externalOrderId": "someOrderId",
      "lastUpdated": "2022-11-15T05:41:36.304Z",
      "orderId": "8700b3b7-5252-4f14-88be-23b452bae88f",
      "patientId": "d9c8cd04-a792-4bc9-af18-49f4610b7338",
      "requestId": "a541209e-e177-41cd-abd3-bad3ffc8391e",
      "requestStatus": "CANCELLED",
      "terminationReason": "CANCELLED_DUPLICATE"
    },
    {
      "coverageStartDate": "2022-01-01",
      "coverageEndDate": "",
      "documentFetchDate": "2022-11-17T05:14:53.906Z",
      "documentId": "6375c34d3889960001ea73b8",
      "documentType": "CCD",
      "externalOrderId": "15,855",
      "lastUpdated": "2022-11-16T06:04:45.869Z",
      "orderId": "beadfb56-0117-42c7-bb3d-161ba70de325",
      "patientId": "0dd90ec4-908f-485b-bb04-f1be9c7a596f",
      "requestId": "e5204137-e348-400c-b7db-18c33397e1fd",
      "requestStatus": "DATA_RETR",
      "terminationReason": ""
    },
		{
      "coverageStartDate": "2022-01-01",
      "coverageEndDate": "",
      "documentFetchDate": "2022-11-17T05:14:53.906Z",
      "documentId": "6375c34d3889960001ea73b9",
      "documentType": "ENCOUNTER_CCD",
      "externalOrderId": "15,855",
      "lastUpdated": "2022-11-16T06:04:46.316Z",
      "orderId": "beadfb56-0117-42c7-bb3d-161ba70de325",
      "patientId": "0dd90ec4-908f-485b-bb04-f1be9c7a596f",
      "requestId": "e5204137-e348-400c-b7db-18c33397e1fd",
      "requestStatus": "DATA_RETR",
      "terminationReason": ""
     }    
  ]
}

(NOTE: For more official examples of API response json, see the API Reference.)

nextStartingTimestamp is the value you should use as startingTimestamp when making your next Changes call.

results will be an array of items which have changed since the startingTimestamp. If there are no changes, the results element will be an empty array.

Requests which have had a Status change will appear with the requestStatus populated. Status values which Greenlight reports include:

• CRED_SKIPPED - the end user passed over this Request without entering credentials or granting access. You may need to have the patient return to your app (and the Greenlight app) to finish the process.
• CRED_FAILED - the credentials the end user provided to Greenlight cause a login error from the portal. You must have the patient return to your app and the Greenlight app to resolve this.
  • The Greenlight app will explain the needed action and help the patient complete it.
• FHIR_TOKEN_EXPIRED - the token the end user granted to Greenlight has expired. You must have the patient return to your app and the Greenlight app to resolve this.
  • The Greenlight app will explain the needed action and help the patient complete it.
• DATA_RETR - this is primarily used to indicate there are new or updated FHIR R4 resources available to fetch. For customers using CCDs, ignore these messages and work directly with the messages containing the document Ids.
• DATA_UNAV_2FA - This portal account is set up with multi-factor authentication. Greenlight suggests sending the patient instructions in this case. Patients can often disable the 2FA setting in their patient portal account long enough for Greenlight's automatic retry process to pick up records, then turn it back on.
  • The Greenlight app can also handle this situation, if you simply bring the patient back to your app and redirect them. Greenlight will provide the patient online instructions and a link to their portal, to complete the tasks.
• DATA_UNAV_USER_INTERVENTION_NEEDED - The end user needs to perform some task in the portal before Greenlight can retrieve the records. Greenlight suggests sending the patient instructions in this case. Greenlight's automatic retry process should retrieve records soon after the patient completes the needed task.
  • The Greenlight app can also handle this situation, if you simply bring the patient back to your app and redirect them. Greenlight will provide the patient online instructions and a link to their portal, to complete the task.
• DOB_CHECK_FAILED - Greenlight detected a discrepancy between the date of birth in the records and the date of birth on file for this patient. The end user needs to log back in and re-enable the connection in their FHIR portal before Greenlight can make another attempt to retrieve records. The most common cause is a patient selecting the FHIR access for the wrong family member. Greenlight suggests sending the patient instructions in this case. When this error is triggered, Greenlight does not store records retrieved and discards the FHIR authorization, preventing further retrieval attempts until the patient returns to the app.
  • The Greenlight app can also handle this situation, if you simply bring the patient back to your app and redirect them. Greenlight will provide the patient online instructions and a link to their portal, to complete the task again.
• CANCELLED - Greenlight or the end user have cancelled this Request, stopping all activity.
• CLOSED - Greenlight has closed this Request. Data fetching is still allowed, for data already retrieved

Requests which have new documents will contain documentId, documentType, documentFetchDate, coverageStartDate, and coverageEndDate. Use these values to call Fetch a document, to retrieve the contents of the CCD. See the Fetch Document workflow and the Fetch a document section of the API Reference.

Coverage Dates - Document "Coverage" dates refer to the time period represented in the CCD. Typically an Encounter CCD contains a short span of time (often a single day) representing data for one medical event. Summary CCDs refer to broader ranges, often from the date the patient's records were started at the facility until the latest medical event.

Termination Reason - This value is only populated on CANCELLED Status Requests. Requests can be cancelled by the patient, by the customer, and by the Greenlight platform (automation). The three automated cancellation reasons are:

• CANCELLED_DUPLICATE - Indicates that the Request would have retrieved the same records as another active Request on the same Order, so the platform cancelled it. (Two Requests with different Coverage Dates set on them will never be seen as duplicates, even if they would have retrieved the same, or a subset of the same records.)
• CANCELLED_CONFIDENCE_RED - Indicates the Request was for a healthcare location that Greenlight cannot access.
• CANCELLED_NO_ACTIVITY - Greenlight allows customers to set a time limit for Requests, after which the platform will cancel the Request, so there is an announcement in the Changes API. This allows customers to move on to other retrieval methods if the patient fails to engage in the process.

Handling Duplicates

There is a small chance that responses to subsequent Changes calls will contain duplicate entries. To check for duplicates, the requestId and lastUpdated should always be unique.

Here are two scenarios we've seen that can create duplicates: a. Your system may have sent an older "from" time for Changes, in which case your system might retrieve those documents and events a second time. b. There is a tiny chance that Greenlight would send a duplicate in a later Changes response because it is exactly on the "startingTimestamp" mark. We err on the side of alerting you twice rather than missing an event.

Changes by Request

The Changes by Request endpoint will return all data and document items that are new or updated since your start time. You can set start time (required) and end time, and cover a period up to a year long.

The response is in the same format as Changes Since (above), but leaves out Status changes. For R4, where a resource might have been mentioned in Changes several times over the timeframe, only the most recent entry is returned. When you fetch an R4 resource you always get the current state of the data, so you only need one Changes reference to prompt you to fetch it.