Leads

The people your workspace talks to who are not yet customers.

The lead object

{
  "id": "ent_ba2kccpsr4",
  "name": "Ana Souza",
  "attributes": [
    { "type": "phone", "label": "mobile", "value": "+5562981226055" },
    { "type": "email", "label": "work", "value": "ana@example.com" }
  ],
  "customFields": { "source": "Instagram" },
  "chatId": "cht_ov7cf39akc",
  "createdAt": "2026-10-18T15:36:40.948Z"
}

id: string, required
The lead's id, starting with ent_.
name: string, required
The lead's name.
attributes: array, required
The lead's phone numbers, emails and other details, each with a type (phone, email, url…), a label and a value. Phones are in E.164. New types may be added: skip one you do not know.
customFields: object, required
The values of the workspace's custom lead fields, by field slug.
chatId: string | null, required
The lead's most recent conversation, starting with cht_.
createdAt: string, required
When the lead was created, in ISO 8601.

List leads

GET/leads

The workspace's leads, newest first, a page at a time. See Pagination.

search: string
Matches the name, an email or a phone number. At most 100 characters.
limit: integer
Leads per page, from 1 to 100. Defaults to 20.
cursor: string
The nextCursor of the previous page.

curl "https://api.swite.co/v1/leads?search=Ana&limit=10" \
  -H "Authorization: Bearer $SWITE_API_KEY"

Create a lead

POST/leads

The phone is checked on the workspace's WhatsApp channel before anything is saved. A number that is not on WhatsApp, or that another lead or contact already has, is refused. A created lead gets a conversation on the channel of the workspace's default department, whose id is its chatId. Nothing is sent to the lead.

name: string, required
The lead's name.
phone: string, required
The lead's phone number, with its country code. Any common format is accepted, and it is stored in E.164.
email: string
The lead's email.
customFields: object
Values by custom field slug, checked against the workspace's lead fields.

curl https://api.swite.co/v1/leads \
  -H "Authorization: Bearer $SWITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Souza",
    "phone": "+55 62 98122 6055",
    "email": "ana@example.com",
    "customFields": { "source": "Instagram" }
  }'

Returns 201 with the lead. It fails with 409 lead.phone_already_exists, 422 lead.phone_not_on_whatsapp, entity.no_connected_channel or custom_field.invalid_values, or 503 lead.whatsapp_unavailable. See Errors.

Get a lead

GET/leads/{id}

curl https://api.swite.co/v1/leads/ent_ba2kccpsr4 \
  -H "Authorization: Bearer $SWITE_API_KEY"

Returns 200 with the lead, or 404 entity.not_found.

Update a lead

PATCH/leads/{id}

Only the fields you send change. A new phone is checked as on create, and a refused update saves nothing.

name: string
The lead's new name.
phone: string
The lead's new phone number.
email: string | null
The lead's new email; null removes it.
customFields: object
Values by custom field slug. Fields you leave out keep their values.

curl -X PATCH https://api.swite.co/v1/leads/ent_ba2kccpsr4 \
  -H "Authorization: Bearer $SWITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": null }'

Returns 200 with the lead. It fails as create does, with 404 entity.not_found, and with 409 lead.changed_concurrently when another request changed the lead at the same moment.

Delete a lead

DELETE/leads/{id}

Deletes the lead for good, with its conversations, messages and tickets.

curl -X DELETE https://api.swite.co/v1/leads/ent_ba2kccpsr4 \
  -H "Authorization: Bearer $SWITE_API_KEY"

Returns 204 with no body, or 404 entity.not_found.