Delete a contact
DELETE /v1/contacts/{id}
Soft-deletes by default: the contact is deactivated and archived, keeping its
message history and any deals that reference it, and it disappears from
GET /v1/contacts unless you pass includeInactive=true.
Pass permanent=true to erase the contact together with its conversations,
DMs, tags and timeline. If another record still points at the contact the
permanent delete returns 409 and nothing is removed - archive it instead.
Emits contact.deleted with mode set to archived or deleted. Requires
scope contacts:write.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Header Parameters
Section titled “Header Parameters ”Act on this workspace’s shared CRM pool. Membership is verified on every request, so an id you do not belong to falls back to personal scope rather than widening access. Omit it to use your default workspace. Applies to every CRM endpoint, not only the ones that list it here.
Query Parameters
Section titled “Query Parameters ”Erase the record instead of archiving it. Irreversible.
Responses
Section titled “ Responses ”Contact deleted.
object
Missing or invalid bearer token.
Standard error envelope for all v1 error responses.
object
Machine-readable error code.
Human-readable explanation of the error.
Optional structured context (field-level validation errors, etc.).
Example
{ "error": "unauthorized", "message": "Invalid bearer principal"}The API key does not have the required scope for this operation.
Standard error envelope for all v1 error responses.
object
Machine-readable error code.
Human-readable explanation of the error.
Optional structured context (field-level validation errors, etc.).
Example
{ "error": "forbidden", "message": "scope contacts:write is required"}The requested resource does not exist or is not owned by the caller.
Standard error envelope for all v1 error responses.
object
Machine-readable error code.
Human-readable explanation of the error.
Optional structured context (field-level validation errors, etc.).
Example
{ "error": "not_found", "message": "contact not found"}The request collides with existing state: a duplicate externalId, an Idempotency-Key replayed with a different body or still in flight, or a permanent delete blocked by records that still reference the contact.
Standard error envelope for all v1 error responses.
object
Machine-readable error code.
Human-readable explanation of the error.
Optional structured context (field-level validation errors, etc.).
Example
{ "error": "conflict", "message": "a contact with externalId 'shopify-cust-88213' already exists", "details": { "existingContactId": 4821 }}Per-key rate limit exceeded. Retry after the time indicated by X-RateLimit-Reset.
Standard error envelope for all v1 error responses.
object
Machine-readable error code.
Human-readable explanation of the error.
Optional structured context (field-level validation errors, etc.).
Example
{ "error": "rate_limited", "message": "rate limit exceeded"}Headers
Section titled “Headers ”Maximum requests allowed per minute for this key.
Requests remaining in the current window.
Unix timestamp (seconds) when the rate limit window resets.