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.
Before you start
You'll need two things to hand:
An API token
The ID of the backup job you're erasing records from
See Getting started with the Data Backup API for how to get both.
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.
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": "<jobId>",
"RecordIds": ["<RecordId1>", "<RecordId2>"],
"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/<RequestId>/status
This returns the current status of the request:
{"RequestId":"5872d0a8-bc64-4766-bbee-8aefd4ee1e97", "RequestStatus":"Scheduled"}
The possible statuses are:
Status | Meaning |
| The request is within its grace period. It can still be cancelled from the job's Audit history page in Gearset. |
| The grace period has passed and the records are queued for erasure. |
| The records are currently being erased. |
| All records in the request have been erased. |
| Some records were erased, but others failed. Check the job's audit history for details. |
| None of the records could be erased. Check the job's audit history for details. |
| 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.