Skip to content
ThreadkiteThreadkite Docs

Delete a contact and their data

POST
/v1/contacts/{id}/erase
curl --request POST \
  --url https://api.threadkite.app/v1/contacts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/erase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "confirm": "ERASE", "includeDuplicates": true }'

Deletes the contact’s messages, files, chat transcripts, call recordings (at Twilio too), form submissions, lead emails and consent details, with the contacts merged with it and (unless includeDuplicates is false) other contacts with the same email address or phone number. Counts and reports stay correct. Use it to honour an erasure request. Runs in the background: poll GET /v1/privacy/requests/{id}; a contact.erased webhook follows for each contact. Cannot be undone. If they get in touch again, they are a new contact.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
confirm
required

The contact’s name, or ERASE, typed to confirm

string
>= 1 characters <= 200 characters

Example 

ERASE
includeDuplicates

Also delete other contacts with the same email address or phone number (the same person entered twice)

boolean
default: true

Responses

Section titled “Responses”

202

Section titled “202”
Media typeapplication/json
object
id
required
string format: uuid
kind
required
string
Allowed values: erasure export
status
required

queued and running while the worker is on it, done, failed (run it again), or expired (an export past its download date)

string
Allowed values: queued running done failed expired
contactId
required

The contact it was asked for

string format: uuid
contactName
required

The contact’s name now (null once their data is deleted)

string
nullable
contactIds
required

Every contact covered (merged and same-person contacts too)

Array<string>
requestedBy
required

Who asked: a team member or an API key

string
requestedByYou
required

Whether you asked for it (only you can download your export)

boolean
counts
required
object
contacts

Contacts covered (merged and same-person contacts too)

number
threads
number
messages

Messages, notes and events, including chat transcripts

number
attachments

Files they sent or were sent

number
chats

Website assistant chats

number
calls

Calls (kept for counts; their number and transcript go)

number
twilioRecordings

Recordings and voicemails deleted in your Twilio account

number
recordingsLeftAtProvider

Recordings Threadkite can’t delete (ones in an account that is no longer connected)

number
recordingsNotRemoved

Recordings a provider has not deleted yet (retried daily)

number
transcripts

Voicemail transcripts

number
formSubmissions

Contact form submissions

number
leadEmails

Lead emails as they arrived

number
marketplaceDeals

Marketplace conversations

number
consents

Consent records (an opt-out is kept, without its details)

number
consentEvents

Consent history events (every change and its proof)

number
externalIds

Ids in other systems

number
links

Linked records (deals, invoices) on their threads

number
tasks

Tasks on their threads (titles and notes cleared)

number
appointments

Appointments with them (notes cleared)

number
scheduledMessages

Replies to them not sent yet (deleted)

number
aiDrafts

Replies the AI drafted for the team on their threads (deleted)

number
contactItems

Things they own (deleted)

number
filesDeleted

Files deleted from storage

number
events

Events about them (an export)

number
automations

Automations they went through (an export)

number
bulkMessages

Bulk messages they were sent, or kept from (an export)

number
videos

Videos sent to them (an export)

number
packItems
required

What the organisation’s industry pack holds about them besides counts (only what there is)

Array<object>
object
key
required

Stable, and namespaced by the pack that holds it

string
label
required

What it is, in plain words

string
count
required
integer
<= 9007199254740991
notes
required

Plain-English notes for you

Array<string>
recordingsLeftAtProvider
required
Array<object>
object
callId
required
string format: uuid
provider
required
string
nullable
Allowed values: twilio
recordingId
required

The id to find it by in the provider account (Twilio RecordingSid)

string
fileSize
required

An export’s size in bytes

number
nullable
expiresAt
required

When an export’s download stops working

string format: date-time
nullable
canDownload
required

An export you can download now

boolean
createdAt
required
string format: date-time
completedAt
required
string format: date-time
nullable

Example 

{
  "kind": "erasure",
  "status": "queued",
  "packItems": [
    {
      "key": "property.viewings",
      "label": "Viewings"
    }
  ],
  "recordingsLeftAtProvider": [
    {
      "provider": "twilio"
    }
  ]
}

400

Section titled “400”

The confirmation is not the contact’s name or ERASE (code confirmation_mismatch)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

401

Section titled “401”

Missing or invalid API key

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

402

Section titled “402”

The organisation is on the Free plan (code upgrade_required)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
feature
required

The feature that needs Pro

string
nullable
Allowed values: extraSeats connections aiAssistant aiReplies rules fullReports api inboxes bulkMessages videoMessages
upgradePath
required

Where to upgrade or pay, in the web app

string

Example 

{
  "statusCode": 402,
  "code": "upgrade_required",
  "message": "Connections are part of Pro. Upgrade to connect texts, calls and more.",
  "feature": "extraSeats",
  "upgradePath": "/settings/billing"
}

403

Section titled “403”

The key does not have the scope (or the person the permission)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

404

Section titled “404”
Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

409

Section titled “409”

Already deleted

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

429

Section titled “429”

Rate limit reached

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
retryAfter
required

Seconds until another request will be accepted

number

Example 

{
  "statusCode": 429,
  "code": "rate_limited",
  "message": "Too many requests. Each key can make 120 requests a minute; try again in 12 seconds.",
  "retryAfter": 12
}