Considerations and requirements

You need any tier of a Gearset Backup license to use this feature.
The Backup API is currently only supported for personal access tokens - the Backup scope isn't available on team access tokens.
The Backup API is not currently available for teams in our HIPAA data residency region.

The Backup API lets you erase records from your Gearset data backups programmatically, as part of your compliance and legal requirements - for example, responding to GDPR or CCPA "right to be forgotten" requests. Instead of finding and deleting records by hand in the Gearset app, you can integrate backup record erasure into your own data compliance workflows, such as a Salesforce Flow or an internal tool that processes data subject requests end to end.

If you only need to delete records occasionally, the in-app flow described in Deleting a record from a data backup job may be all you need - the API is aimed at teams who want to automate this process or handle requests at volume.

How erasure requests work

When you submit an erasure request via the API, the records aren't deleted immediately. Every request has a grace period (48 hours by default) before any data is removed. This acts as a safety net: a misconfigured integration could otherwise erase large numbers of records with no way back, since deletion from a backup is permanent and irreversible.

During the grace period the request shows as Scheduled, and it can be cancelled from the backup job's Audit history page in Gearset. Once the grace period has passed, the request is processed automatically - you don't need to run the backup job yourself - and the records are permanently erased from all of the job's backup data, including previous backup runs.

Screenshot showing the Audit history tab of a backup job with a scheduled erasure request

Making your first Backup API requests

To start with, you need an API access token with the Backup scope, which you can generate by following our tutorial Creating a Gearset API access token.

Once you have that, you're ready to start making requests. The Backup API is a REST API that accepts JSON messages over HTTPS, so we'll be using the curl program to demonstrate its use. The curl program is installed by default on Linux, Windows, and macOS command lines. Our full API reference gives a list of the endpoints available, and also lets you run them.

Finding your backup job ID

Erasure requests are made against a specific backup job, so first we need the ID of the job that holds the records. Navigate to the Data backup jobs page in Gearset and find the job you are interested in. You can copy the job ID to the clipboard with the Copy job ID button:

A job card on the Data backup jobs page showing a summary of the job and the button to copy a job ID

Scheduling an erasure request

We'll schedule the erasure of two records from the backup job. Copy the following and run it, making sure to replace the token, job ID, and record IDs with your own:

curl -H "Authorization: token <APIToken>" \
     -H "Content-Type: application/json" \     
     https://api.gearset.com/public/backup/data-compliance/request/erasure \ 
     -d '{
           "JobId": "263ba833-0bd6-4361-ab22-6ef7ca20b6e8",
           "RecordIds": ["0011U00000TFV7MQAX", "0011U00000TFV7MQAY"], 
           "Reason": "GDPR erasure requested by data subject."
         }'

A few things to note about the request body:

RecordIds takes between 1 and 1,000 Salesforce record IDs per request.
Reason is optional (maximum 256 characters). It's recorded against the request and shown in the job's audit history, so it's a good place to reference your internal case or ticket number.
GracePeriod is an optional ISO 8601 duration. If you leave it out, the default of 48 hours (PT48H) is used. You can set anything from 24 hours (PT24H) to 28 days (P28D) - for example, "GracePeriod": "P7D" schedules the erasure for a week's time. Values outside that range are rejected with a 400 response.

When you've run the command you should get a response like this:

{"RequestId":"5872d0a8-bc64-4766-bbee-8aefd4ee1e97"}

Save this value - it identifies your erasure request, and we'll use it next to check on its progress.

Checking the status of an erasure request

To find out where a request has got to, query its status using the request ID from the previous step:

curl -H "Authorization: token <APIToken>" https://api.gearset.com/public/backup/data-compliance/request/5872d0a8-bc64-4766-bbee-8aefd4ee1e97/status

This returns the current status of the request:

{"RequestId":"5872d0a8-bc64-4766-bbee-8aefd4ee1e97", "RequestStatus":"Scheduled"}

The possible statuses are:

Status	Meaning
`Scheduled`	The request is within its grace period. It can still be cancelled from the job's Audit history page in Gearset.
`Pending`	The grace period has passed and the records are queued for erasure.
`InProgress`	The records are currently being erased.
`Removed`	All records in the request have been erased.
`PartialFailure`	Some records were erased, but others failed. Check the job's audit history for details.
`AllFailed`	None of the records could be erased. Check the job's audit history for details.
`Cancelled`	The request was cancelled before it was processed. No records were erased.

And that's it - you've successfully used the Backup API to schedule an erasure request and track it through to completion.

Getting started with the Gearset Backup API