Candidate Deletion Events

Deleting a candidate is asynchronous. DELETE /v1/candidates/... returns 202 as soon as the work is queued, and the erasure then runs across several stores — the candidate record and everything written about them, every version of every CV and upload, the search index, and the message transcript held by our SMS provider.

This event is how you learn it finished.

Available Events

Event	Description
`CANDIDATE_DELETED`	A candidate has been erased and no longer exists in your data

CANDIDATE_DELETED

Sent once the whole erasure has completed. Until it arrives, treat the deletion as still in progress.

One event per candidate, not per request. DELETE /by-email/{email} can match several candidates; each one is erased separately and sends its own event.

Correlate on candidateProfileId: the 202 response lists the ids it queued, and each event names one of them. That tells you how many events to expect and which is which.

Payload

{
  "event": "CANDIDATE_DELETED",
  "eventId": "evt_abc123",
  "eventTimestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "recordId": "candidate_xyz789",
    "organizationId": "org_123456",
    "candidateProfileId": "candidate_xyz789",
    "externalId": "your_external_candidate_id",
    "requestedBy": "email"
  }
}

Data Fields

Field	Type	Description
`candidateProfileId`	string	The Popp id of the candidate that was erased
`externalId`	string \| null	Your own id for this candidate, as it was before erasure. Null if you never set one
`requestedBy`	string	Which kind of address the deletion was made against: `id`, `externalId`, `email` or `phoneNumber`

externalId is echoed back because the candidate is gone by the time you receive this — there is nothing left to look up, so the event has to carry what you need to match it to your own records.

requestedBy tells you which of your call sites issued the deletion, which is useful when several of them can delete. It does not identify an individual request — two by-email deletions both report email. Use candidateProfileId to tie an event to a request.

No personal data

The payload deliberately carries no name, email address or phone number. Sending those in a deletion event would copy the very data the request was made to erase into your webhook logs.

This is also why a by-email or by-phone-number deletion does not echo the address you searched on — only requestedBy, naming the kind of address used.

If the event never arrives

There is no failure event. An erasure that cannot complete is escalated internally rather than reported over a webhook, because a partial erasure is a matter for our team to finish, not something you can resolve by retrying.

If you expected an event and it has not arrived, GET /v1/candidates/{id} is the check: a 404 means the candidate is gone. If it still returns 200 well after the request, contact Popp support.