Guide on how to detect deleted records with syncs
nango.batchDelete()
(full reference) inside the sync script.
nango.batchDelete()
if the external API supports one of the following:
GET /entities/deleted?since=...
)is_deleted
, archived
, etc.trackDeletes
flag (full reference).
trackDeletes
does not work with incremental syncs because fetching the data incrementally prevents performing a diff and automatically detecting deletions.record._metadata.deleted === true
.trackDelete
Nango only performs deletion detection (the “diff”) if a sync run completes successfully without any uncaught exceptions.If you’re using trackDelete
, exception handling becomes critical:try/catch
, re-throw exceptions that indicate incomplete data.trackDeletes
safely
If some records are incorrectly marked as deleted due to the trackDeletes
feature, you can trigger a full resync (via the UI or API) to restore the correct data state.However, because trackDeletes
relies on logic in your sync scripts—and mistakes there can lead to false deletions—we strongly recommend not performing irreversible destructive actions (like hard-deleting records in your system) based solely on deletions reported by Nango. A full resync should always be able to recover from issues.Symptom | Likely cause |
---|---|
Records that still exist in the source API are shown as deleted in Nango | trackDeletes was enabled on an incremental sync, or a full refresh run silently failed |
You never see deleted records | Check if deletion detection is implemented for the sync. |