Sales
Add a tag to a lead
Adds a tag to a lead and returns the lead. A tag linked to a queue moves the lead into that queue. Answers 403 desk.sales_off while Sales is switched off.
Requires: desk.write scope, Converse or Contacts licence, Pro plan.
Authorization
bearerAuth AuthorizationBearer <token>
A SautiDesk API key. An owner or admin makes it under Settings in SautiDesk for a named person and picks the scopes. The key is shown once. Send it as Authorization: Bearer <key>. It acts as that person and as nobody else.
In: header
Path Parameters
id*string
The lead's id (a UUID).
Request Body
application/json
Response
OK
Example
{ "id": "3f2b8c1e-5a4d-4e7b-9c10-2d6a8e4f1b37", "ref": "TCK-4471", "status": "open", "contact_id": "e370603e-5791-443e-9fb1-26dedb014cd9", "contact_name": "Amina Wanjiru", "contact_number": "+254712345678", "stage_id": "bfed4519-9865-4baf-930a-0ac87c16a093", "stage_name": "example", "stage_kind": "example", "owner_id": "1dc86aaf-2f65-4b1b-9ef7-7dabe869da64", "owner_name": "Wanjiku Mwangi", "queue_id": "c70c2d37-4d65-4ba4-9843-5e8aaf2dae40", "queue_name": "Support", "source_id": "2e953c78-1606-4098-9709-061f8b3d7860", "source_name": "example", "temperature": "example", "value_minor": 1, "currency": "KES", "lost_reason_id": "b015e632-7186-485b-90f6-cc9f3b883d90", "lost_reason": "example", "lost_note": "example", "company": "Example Ltd", "name": "Amina Wanjiru", "tags": [ { "id": "3f2b8c1e-5a4d-4e7b-9c10-2d6a8e4f1b37", "name": "Amina Wanjiru", "colour": "#1D4ED8" } ], "next_follow_up": { "task_id": "ad869580-754f-478d-9f53-ece308d91edc", "due_at": "2026-10-14T08:30:00Z", "note": "Hi Amina, your order has shipped.", "activity_type_id": "7dc83545-5e5c-4ee0-9e92-704cc08faaf7", "activity_type_name": "example", "assignee_id": "fe310313-9e12-412d-969a-cdb7558caaca", "overdue": false }, "opened_at": "2026-10-14T08:30:00Z", "opened_by": "d30d083f-3105-4b54-925d-0f1bdfa2fb14", "closed_at": "2026-10-14T08:30:00Z", "updated_at": "2026-10-14T08:30:00Z"}FieldTypeDescription
idrequiredstring (uuid)refrequiredstringstatusrequiredstringThe status to set.contact_idrequiredstring (uuid)The id of the contact the task is about.contact_namerequiredstringcontact_numberstringstage_idrequiredstring (uuid)stage_namerequiredstringstage_kindrequiredstringowner_idrequiredstring (uuid) | nullowner_namestringqueue_idrequiredstring (uuid) | nullThe id of the queue that receives what arrives here.queue_namestringsource_idrequiredstring (uuid)source_namerequiredstringtemperaturerequiredstringvalue_minorrequiredintegercurrencyrequiredstringThe currency code of the money in this report, for example KES. Write money figures with it. Left out when the report has no money.lost_reason_idrequiredstring (uuid) | nulllost_reasonstringlost_notestringcompanyrequiredstringThe company the contact works for.namerequiredstringA name for it.tagsrequiredobject[]idrequiredstring (uuid)namerequiredstringA name for it.colourrequiredstringnext_follow_uprequiredanytask_idrequiredstring (uuid)due_atrequiredstring (date-time)When it is due, as a date and time with an offset, for example 2026-10-15T09:00:00+03:00.noterequiredstringA note.activity_type_idrequiredstring (uuid) | nullactivity_type_namerequiredstringassignee_idrequiredstring (uuid) | nullThe id of the person the task is for.overduerequiredbooleanopened_atrequiredstring (date-time)opened_byrequiredstring (uuid) | nullclosed_atrequiredstring (date-time) | nullupdated_atrequiredstring (date-time)curl -X POST "https://api.sautidesk.com/v1/desk/leads/string/tags" \ -H "Content-Type: application/json" \ -d '{ "tag_id": "7ba3d176-e23c-44bf-9f3c-6811cd816541" }'