Skip to main content
DELETE
Delete contact
DELETE /candidates/{id} is a permanent alias of this endpoint and keeps working unchanged, with the same scopes and the same response. See Resource names.
Permanently deletes a contact. This action cannot be undone, and it takes the contact’s conversations with it.

Overview

This endpoint removes a contact and their personal data from your account outright. It is a hard delete, not a flag.

Use Cases

  • Remove duplicates: clean up a contact entered twice
  • GDPR compliance: satisfy an erasure request
  • Cleanup: drop contacts you no longer hold a reason to keep

What Else Is Deleted

Deleting a contact deletes every conversation they had. Their transcripts, recordings and analyses go with them, along with their job assignments. Nothing of theirs is readable through the API afterwards: a later GET /conversations?contactId=… for that contact returns nothing, and there is no endpoint that brings any of it back.If you need the call history, export it before you issue the delete.
Deleted rows are archived internally first — a deletion audit log and an archive table that exist for our own compliance obligations. Neither is reachable through the public API, so neither is a way for you to get the data back.

GDPR Considerations

This is the deletion the API offers, and it is the one to reach for on an erasure request. Note the internal archive above before you promise a data subject that nothing remains anywhere: if your obligation is erasure from our systems rather than from your integration, raise it with our support team rather than assuming this call has satisfied it.

Company Isolation

You can only delete contacts belonging to your API key’s company. Ownership is validated first.

Error Scenarios

  • 404 Not Found: the contact does not exist, or has already been deleted
  • 403 Forbidden: the contact belongs to a different company

Contacts Resource Guide

Learn about managing contacts

List Contacts

Browse your contacts

Create Contact

Create a new contact

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

id
string<uuid>
required

Query Parameters

companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Response

200 - application/json
id
string<uuid>
required

Id of the deleted resource

deleted
enum<boolean>
required

Always true; a failed delete answers with an error status

Available options:
true
Example:

true