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.	`POST /r4/$purge`
Purge Status	Track the status of your Purge operation using the Job ID from your purge job.	`GET /r4/$purge/[job ID]`
Retry	If one or more batches in your purge job were not deleted, try the Purge operation again.	`PUT /r4/$purge/[job ID]`
Cancel	Stop a Purge operation that’s running.	`DELETE /r4/$purge/[job ID]`

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.

https://[api-domain-name]/r4/$purge

Purge API example

https://api.1up.health/r4/$purge

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
`client_id`	The client ID for your account. This is a required parameter for the header authentication type.
`client_secret`	The secret key for your account. This is a required parameter for the header authentication type.

Header

client_id

The client ID for your account.

This is a required parameter for the header authentication type.

client_secret

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.
`_before`	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 (`meta.lastUpdated`). Example — `_before=2022-01-01` The `_before` parameter must be used with the `_type` parameter. If you don’t specify a date, all resources are deleted.

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.

_before

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 (meta.lastUpdated).

Example — _before=2022-01-01

The _before parameter must be used with the _type parameter.

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.

Purge operation request with token authorization

To start a purge job using an authorization bearer token, run:

1
2
curl --location --request POST 'https://[api-domain-name]/r4/$purge' \
--header 'Authorization: Bearer [token ID]'

Bearer token authentication request example

1
2
curl --location --request POST 'https://api.1up.health/r4/$purge' \
--header 'Authorization: Bearer wxyz'

Purge operation request with header authorization

To start a purge job using header authentication, run:

1
2
3
4
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]'

Header authorization request example

1
2
3
4
curl --location --request POST 'https://api.1up.health/r4/$purge' \
--header 'client_id: exampleClientID' \
--header 'client_secret: exampleSecret123498765' \
--header 'x-oneup-user-id: user125id'

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

Successful Purge

Example successful purge response message

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "job": {
        "userId": "user125id",
        "clientId": "c123",
        "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,
        "initializedOn": null
    }
}

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.

Purge operation request example for the _type Patient

1
2
3
4
curl --location --request POST '<https://api.1uphealthdev3.com/r4/$purge?_type=Patient'> \
--header 'client_id: c123' \
--header 'client_secret: ***' \
--header 'x-oneup-user-id: user125id'

Purge operation response example for the _type Patient

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "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.

Purge operation Status request with token authorization

To get the status of a purge job using a Bearer token, run:

1
2
curl --location --request GET 'https://[api-domain-name]/r4/$purge/[job ID]' \
--header 'Authorization: Bearer [token ID]'

Purge operation Status request example using a token

1
2
curl --location --request GET 'https://api.1up.health/r4/$purge/f707145c-7c51-44ae-8bcd-9a55bff81974' \
--header 'Authorization: Bearer wxyz'

Purge operation Status request with header authorization

To get the status of a purge job using header credentials, run:

1
2
3
4
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]'

Purge operation Status request example with header credentials

1
2
3
4
curl --location --request GET 'https://api.1up.health/r4/$purge/f707145c-7c51-44ae-8bcd-9a55bff81974' \
--header 'client_id: exampleClientID' \
--header 'client_secret: exampleSecret123498765' \
--header 'x-oneup-user-id: user125id'

Purge operation Status response example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "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.

Retry a failed purge job with token authorization

To retry a failed purge job using an authorization token, run:

1
2
curl --location --request PUT 'https://[api-domain-name]/r4/$purge/[job ID]' \
--header 'Authorization: Bearer [token ID]'

Purge operation Retry request example with an token authorization

1
2
curl --location --request PUT 'https://api.1up.health/r4/$purge/f707145c-7c51-44ae-8bcd-9a55bff81974' \
--header 'Authorization: Bearer wxyz'

Retry a failed purge job with header authorization

To retry a failed purge job using header authorization, run:

1
2
3
4
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]'

Purge operation Retry request example with header authorization

1
2
3
4
curl --location --request PUT 'https://api.1up.health/r4/$purge/f707145c-7c51-44ae-8bcd-9a55bff81974' \
--header 'client_id: exampleClientID' \
--header 'client_secret: exampleSecret123498765' \
--header 'x-oneup-user-id: user125id'

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.

Cancel a purge job with token authorization

To cancel a purge job using an authorization token, run:

1
2
curl --location --request DELETE 'https://[api-domain-name]/r4/$purge/[job ID]' \
--header 'Authorization: Bearer [token ID]'

Purge operation Cancel request example with token authorization

1
2
curl --location --request DELETE 'https://api.1up.health/r4/$purge/f707145c-7c51-44ae-8bcd-9a55bff81974' \
--header 'Authorization: Bearer wxyz'

Cancel a purge job with header authorization

To cancel a purge job using header authorization, run:

1
2
3
4
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]'

Purge operation Cancel request example with header authorization

1
2
3
4
curl --location --request DELETE 'https://api.1up.health/r4/$purge/f707145c-7c51-44ae-8bcd-9a55bff81974' \
--header 'client_id: exampleClientID' \
--header 'client_secret: exampleSecret123498765' \
--header 'x-oneup-user-id: user125id'

Purge operation Cancel request response example

1
2
3
4
5
6
{
    "job": {
        "id": "f707145c-7c51-44ae-8bcd-9a55bff81974",
        "status": "canceled"
    }
}