Skip to main content
Contacts

Delete contact by external user ID

Permanently deletes a contact by their external user ID.

DELETE
/v2/contacts/by-user-id/{userId}

Important: This endpoint only deletes customers (type: "customer"). Leads cannot be deleted using this endpoint.

Path Parameters

  • userId - The external user ID from your system

Deletion Behavior

When a contact is deleted:

  • The contact record is permanently removed
  • Associated data cleanup is triggered asynchronously
  • Comments and posts created by the contact are handled according to retention policies

Response

Returns a deletion confirmation object:

  • id - The ID of the deleted contact
  • object - Always "contact"
  • deleted - Always true

Example Response

{
  "id": "676f0f6765bdaa7d7d760f88",
  "object": "contact",
  "deleted": true
}

Use Case

Use this endpoint when you need to delete a contact using your own system's user identifier, such as when a user deletes their account in your application.

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

userIdstringrequired

External user ID from your system

Maximum string length: 255
Example: usr_12345

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Response

application/json

Success

deletedenum<boolean>required

Indicates the resource was deleted

Available options: true
Example: true
idstringrequired

Unique identifier of the deleted contact

Example: 507f1f77bcf86cd799439011
objectenum<string>required

Object type identifier

Available options: contact
Example: contact

Still need help? Ask the team