Bulk Data Purge (Single Tenant)
This topic is for the single-tenant environment (STE) version of Bulk Data Purge. If your implementation is a multi-tenant environment (MTE), see the topics in Bulk Data Purge (Multi Tenant).
You can use the FHIR Purge API ($purge) endpoint to asynchronously delete your R4 FHIR data from your 1upHealth FHIR Server. When you delete your data, all versions, history, provenances, and binary resources related to the data are removed from the data store. You can include parameters in your Purge operation requests to specify which FHIR resource types or FHIR resources are deleted. You can only use the Purge API for your user ID or client ID.
After you start a purge job, you can monitor the status of the deletion process and review its progress. You can also cancel a purge job or retry a failed job.
The Purge API and deletion process are only supported for R4 data. DSTU2 and STU3 versions are not supported.
Before You Begin
Before you can use the Purge API, you must have a tool (such as Postman) that can connect to the Purge API endpoints and make the appropriate calls for each operation. You must also have your Purge API endpoint URL and the authorization details for the access method type that you want to use.
If you don’t have your API endpoint URL, contact your 1upHealth Implementation Engineer for assistance.
Access Method Options
Before you connect to a Purge endpoint, make sure that you have the correct authorization details for the access type method that you want to use: bearer token authorization or header authorization. You must use the same authorization type that is specified for your application.
Access Type |
Authorization Details |
---|---|
Authorization token |
Bearer token |
Header authentication |
The client ID and client secret (secret key) for your account |
For more information about how to get an access token for Bearer token authentication, see Authentication & Authorization APIs.
For more information about how to get the oneup_user_id
for an app_user_id
for header authentication, see User Management APIs.
Purge Endpoints
The Purge operation supports the following endpoints. Make sure to use the correct endpoint for the Purge operation that you want to execute.
Name |
Description |
Endpoint |
---|---|---|
Purge |
Create a purge job and execute the job for a specific client ID. |
|
Purge Status |
Track the status of your Purge operation using the Job ID from your purge job. |
|
Retry |
If one or more batches in your purge job were not deleted, try the Purge operation again. |
|
Cancel |
Stop a Purge operation that’s running. |
|
Make sure to replace [job ID]
with the ID of your purge job.
When you connect to the Purge endpoints, you use your API URL in the following format.
Run a Purge Job
You can run a purge job to delete all of your R4 version FHIR resources from your 1upHealth FHIR Server. The Purge operation deletes all data and binary resources from the server and is not reversible.
After the data is deleted, it cannot be recovered.
Data or resources that are uploaded to the FHIR Server after you start a purge job are not deleted and remain on the server. If you want to delete the newly uploaded data, you must start a new purge job.
If you previously used the FHIR API Delete endpoint to delete data or a resource from the 1up FHRI Servers, when you use the Purge API to delete data, the version history table (_history
) is not deleted.
You can run only one purge job at a time.
Before you begin, make sure that you have either your bearer token (authorization token option) or your client ID and client secret (header authentication option).
Purge Job Parameters
When you run a Purge operation, you can specify two types of parameters to apply to the purge job: header parameters and query parameters. If you use the header-based authentication method to get access to the 1up FHIR Server, header parameters are required and specify the account to delete resources from. Query parameters are optional and refine the resources that are deleted, regardless of the authentication method you use.
You can include query parameters in your Purge operation requests to specify the FHIR resource types to delete (_type
) or to specify a time frame for data to delete (_before
).
Parameters
Header |
|
---|---|
|
The client ID for your account. This is a required parameter for the header authentication type. |
|
The secret key for your account. This is a required parameter for the header authentication type. |
Query |
|
---|---|
_type
|
Specify the FHIR resource types to delete. Separate multiple resource types with a comma. If you don’t specify a type, all resource types are deleted. |
|
Specify the date of the resources to include in the Purge operation. Only resources that were updated on the FHIR Server before the date you specify are deleted ( Example — The If you don’t specify a date, all resources are deleted. |
Start a Purge Job
To start a Purge operation, you send a POST request to the Purge API endpoint to start the purge job to delete the data. When you send the request, you can also include query parameters to specify which data to delete. If the post request is successful, the purge job automatically begins. If it fails, you can try the request again.
In the following examples, make sure to replace the [text in brackets
with the correct information for your endpoints.
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
To start a purge job using an authorization bearer token, run:
curl --location --request POST 'https://[api-domain-name]/r4/$purge' \
--header 'Authorization: Bearer [token ID]'
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
To start a purge job using header authentication, run:
curl --location --request POST 'https://[api-domain-name]/r4/$purge' \
--header 'client_id: [client ID]' \
--header 'client_secret: [client secret]' \
--header 'x-oneup-user-id: [user ID]'
When your POST request to the Purge API endpoint executes successfully, you receive a Successful purge response message (similar to the following example), and the Purge operation automatically begins.
The response message includes the job ID, which is the id value in the job method. In the following example, the id
is f707145c-7c51-44ae-8bcd-9a55bff81974.
200: OK |
![]() Example successful purge response message |
If your POST request fails, verify that you have specified the correct information in the URL. If your URL is incorrect, you receive a 404 response. If your URL is correct, you can monitor the status of the purge job to find the issue that caused the failure.
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
_type
Patient
{
"job": {
"userId": "user125id",
"clientId": "c123",
"typeList": [
"Patient"
],
"beforeDate": null,
"id": "f707145c-7c51-44ae-8bcd-9a55bff81974",
"status": "in progress",
"retryCount": 0,
"createdOn": "2023-07-31T20:39:34.575Z",
"completedOn": null,
"lastUpdated": null,
"resourceCount": null,
"deletedCount": null,
"initializedOn": null
}
}
Monitor the Status of a Job
After you start a Purge operation, you can connect to the Purge Status API endpoint to monitor the status of a purge job. The purge job status request returns one of the following options.
Status |
Description |
---|---|
In Progress |
The purge job is running. |
Successful |
All batches in the purge job and completed and the requested data has been deleted. |
Failed |
One or more batches haven’t been deleted. |
Canceled |
The purge job has been canceled. |
To get the status of the purge job, you must have the Purge operation id
value from the Successful purge response message you received when you submitted the POST request.
In the following examples, make sure to replace the [text in brackets
with the correct information for your endpoints.
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
To get the status of a purge job using a Bearer token, run:
curl --location --request GET 'https://[api-domain-name]/r4/$purge/[job ID]' \
--header 'Authorization: Bearer [token ID]'
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
To get the status of a purge job using header credentials, run:
curl --location --request GET 'https://[api-domain-name]/r4/$purge/[job ID]' \
--header 'client_id: [client ID]' \
--header 'client_secret: [client secret]' \
--header 'x-oneup-user-id: [user ID]'
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
{
"job": {
"id": "f707145c-7c51-44ae-8bcd-9a55bff81974",
"clientId": "c123",
"userId": "user125id",
"status": "successful",
"retryCount": 0,
"createdOn": "2023-07-31T20:39:34.575Z",
"completedOn": "2023-07-31T20:40:40.208Z",
"lastUpdated": "2023-07-31T20:40:40.299Z",
"resourceCount": 1568,
"deletedCount": null,
"typeList": [
"Patient"
],
"beforeDate": null,
"initializedOn": "2023-07-31T20:39:37.885Z",
"completedBatches": 1,
"failedBatches": 0,
"totalBatches": 1
}
}
Retry a Job
You can run a Retry operation if one or more batches in your purge job are not successfully deleted. If your environment has large data sets, one or more batches in your Purge operation could fail. If your batch fails, you can run a retry job to try the Purge operation again.
In the following examples, make sure to replace the [text in brackets
with the correct information for your endpoints.
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
To retry a failed purge job using an authorization token, run:
curl --location --request PUT 'https://[api-domain-name]/r4/$purge/[job ID]' \
--header 'Authorization: Bearer [token ID]'
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
To retry a failed purge job using header authorization, run:
curl --location --request PUT 'https://[api-domain-name]/r4/$purge/[job ID]' \
--header 'client_id: [client ID]' \
--header 'client_secret: [client secret]' \
--header 'x-oneup-user-id: [user ID]'
Cancel a Job
You can use the Purge Status API endpoint o cancel a Purge operation after it starts. This is the same endpoint that you use to request the status of a purge job that’s already started. Instead of sending a GET request to the endpoint, you send a DELETE request.
In the following examples, make sure to replace the [text in brackets
with the correct information for your endpoints.
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
To cancel a purge job using an authorization token, run:
curl --location --request DELETE 'https://[api-domain-name]/r4/$purge/[job ID]' \
--header 'Authorization: Bearer [token ID]'
![Closed](../../../Skins/Default/Stylesheets/Images/transparent.gif)
To cancel a purge job using header authorization, run:
curl --location --request DELETE 'https://[api-domain-name]/r4/$purge/[job ID]' \
--header 'client_id: [client ID]' \
--header 'client_secret: [client secret]' \
--header 'x-oneup-user-id: [user ID]'