Delete Candidate

Permanently deletes a candidate and everything associated with them. This is irreversible — see the warning on this page for the full list of what is destroyed.

Identify the candidate with exactly one of candidateId, candidateExternalId, or email. Supplying zero or more than one returns 400. All lookups are scoped to the company owning the API key, so you can never delete another company’s records.

candidateExternalId is not guaranteed unique — if several candidates in your company share one, every match is deleted and deletedCount reflects the total.

The response returns a snapshot of each deleted record. This is your only copy: once the call returns, the data is gone from Alex. Note that assets.cleanupSucceeded is false when the database records were removed but some stored files could not be — alert on it if you must guarantee media removal.

POST /deleteCandidate

cURL

cURL

curl --request POST \
  --url https://api.alex.com/v1/api/deleteCandidate \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "candidateId": "clx8f2k1p0000abcd1234efgh",
  "candidateExternalId": "ATS-4471",
  "email": "[e-mail]"
}
'

200

{
  "success": true,
  "code": "DELETED",
  "message": "Deleted 1 candidate record(s).",
  "deletedCount": 1,
  "data": {
    "candidates": [
      {
        "candidateId": "clx8f2k1p0000abcd1234efgh",
        "candidateExternalId": "ATS-4471",
        "email": "[e-mail]",
        "firstName": "Jordan",
        "lastName": "Reyes",
        "phoneNumber": "[phone]",
        "createdAt": "2026-03-14T10:02:11.000Z",
        "sessionIds": [
          "ses_9f2b1c"
        ],
        "applicationIds": [
          "app_4d71ae"
        ]
      }
    ],
    "assets": {
      "resumesDeleted": 1,
      "sessionsCleaned": 3,
      "cleanupSucceeded": true
    }
  }
}

This action is irreversible. Deleting a candidate permanently destroys, with no undo and no way for Alex support to recover it:

• the candidate record and all of their contact details
• every interview session and application belonging to them
• all interview transcripts, scores, feedback, and generated reports
• their stored resume file
• all interview recordings — audio and video

There is no soft delete, no trash, and no recovery window. Once the call returns, the data is gone. Use the snapshot in the response as your own record of what was removed.

Identify the candidate with exactly one of candidateId, candidateExternalId, or email. Supplying none — or more than one — returns a 400.

Scoping

Every lookup is scoped to the company that owns the API key. You cannot delete a candidate belonging to another company, and an identifier that exists elsewhere in Alex but not in your company returns 404.

Duplicate external IDs

candidateExternalId is not required to be unique. If several candidates in your company share one, all of them are deleted and deletedCount reports the total. Use candidateId when you need to target exactly one record.

Confirming media was removed

Database records and stored files are deleted separately. If the records are removed but some files cannot be, the call still succeeds and data.assets.cleanupSucceeded is false. If you must guarantee that recordings and resumes are gone — for a data-retention or GDPR obligation, for example — alert on that flag rather than on the HTTP status alone.

Authorizations

X-API-Key · string · header · required

Body

application/json

Supply exactly one identifier.

candidateId · string

The Alex-side candidate ID, as returned by /candidates.

Example:

"clx8f2k1p0000abcd1234efgh"

candidateExternalId · string

The ATS-side candidate ID you supplied to /inviteCandidate.

Example:

"ATS-4471"

email · string

The candidate's email address. Matched case-insensitively within your company.

Example:

"[e-mail]"

Response

200

application/json

Candidate deleted

success · boolean · required

Example:

true

code · string · required

Example:

"DELETED"

message · string · required

Example:

"Deleted 1 candidate record(s)."

deletedCount · integer · required

Number of candidate records deleted. Greater than 1 only when a non-unique candidateExternalId matched several.

Example:

1

data · object · required

Show child attributes