Skip to main content
Manage custom labels for categorizing and organizing leads. These endpoints allow you to create, list, retrieve, update, and delete lead labels, as well as test AI-powered reply label predictions.

Deleting a label

DELETE /api/v2/lead-labels/{id} deletes the label and the webhooks subscribed to it right away. It then starts a background job of type delete-lead-label. The job moves the label’s leads and Unibox emails to reassigned_status. The response returns the deleted label with a background_job_id. To track the job, call GET /api/v2/background-jobs/{id} with that ID until its status is success or failed. If the job fails, send the same DELETE request again to resume it.
The job moves leads and emails in two passes. The first starts about a minute after the delete. The second runs about 10 minutes later and moves anything that got the old interest status in the meantime. Until the job finishes, some leads and emails still show the deleted label’s interest status.
If you delete the same label again while its job is running or after it failed, you get the same label and background_job_id back, and a failed job resumes. This works only for the member who started the delete or a member who can see all labels. Others get 404 Not Found. The delete returns 409 Conflict when:
  • reassigned_status is a label that is being deleted. Choose another label.
  • Leads are still moving onto this label from another deleted label. Try again in a few minutes.
  • Another change to the same leads is starting. Try again in a moment.

Interest status numbers

Each label gets the next free interest_status number in its range (positive, neutral, or negative). A deleted label’s number is never given to a new label. When a range has no free number left, POST /api/v2/lead-labels returns 409 Conflict with the message No free status is left for this kind of label.
  • Lead Label — field reference for lead label objects

Endpoints