Prerequisites

To call the retention API, first obtain your organization's OrgId and Access Token, as described in the API Authentication documentation.

Create a Retention Job

API documentation for creating a retention job can be found here: Create Job

Retention jobs only run at night. To check the status either subscribe to the RetentionJobCompleted event using a Webhook or periodically poll the GetJob endpoint.

For any given resource, criteria are optional. If no criteria are provided, no extract or purge will occur. In addition, only 10,000 object graphs per resource will be extracted/purged. You will have to devise a strategy to extract/purge data on a go-forward basis. We can work with you to help devise your strategy.

An example post to the endpoint might look like the following:

{
  "jobType" : "Extract",
  "criteria" : {
  	"liveChats" : "ArchivedDateTime gt 2023-01-01T00:00:00Z and ChatTasks/all(x: x/ResolutionStatus eq 'Resolved')",
    "registeredChats" : "ExpiredDateTime gt 2023-01-01T00:00:00Z",
    "smsChats" : "UpdatedDateTime gt 2023-01-01T00:00:00Z or Messages/any(x: x/Timestamp gt 2023-01-01T00:00:00Z)",
    "smsBatches" : "UpdatedDateTime gt 2023-01-01T00:00:00Z"
  }
}

Request Body Explanation

• jobType The type of job to create, which can be either "Extract" or "ExtractPurge".
• criteriaAn object containing criteria for extracting and purging various types of MedChat resources. The criteria format follows OData filter syntax.
  • liveChatsCriteria for extracting and purging LiveChats.
  • registeredChatsCriteria for extracting and purging RegisteredChats.
  • smsChatsCriteria for extracting and purging SmsChats.
  • smsBatchesCriteria for extracting and purging SmsBatches.

A successful post to the endpoint will return a 204 status code and a location header to the new job.

Download Extract File

API documentation for downloading the extract file produced by the retention job can be found here.

The file is a zip archive. The contents of the file will look like this:

LiveChat\
	extract.json
  Files\					-- Files uploaded by the patient.  File name will be a GUID which is refereenced in the extract.json
    file1.jpg   
	  file2.jpg
RegisteredChat
	extract.json
SmsChat\
	extract.json
SmsBatch\
	extract.jon

🚧

Close Retention Job

To finish the lifecycle of the retention job and purge any artifacts created, call the close retention job endpoint. API documentation can be found here. If not called, all artifacts will be cleaned up after 30 days and the job will be set to a closed status.