Leads
| Method | Path | Description |
|---|---|---|
GET | /leads | List leads, newest first. Query: page, limit (max 200), q, verificationStatus, espClass, tagId. The order is fixed, so paging through all pages returns every lead exactly once |
POST | /leads | Bulk create/update up to 1,000 leads (merges by email) |
PATCH | /leads/:id | Update one lead’s fields |
PATCH | /leads/bulk | Update up to 1,000 leads, each found by id or email. Returns updated, unchanged, notFound |
POST | /leads/bulk-delete | Permanently delete up to 1,000 leads by id (owner/admin). Body: leadIds. Returns deleted |
POST | /leads/:leadId/tags | Attach a tag to a lead |
DELETE | /leads/:leadId/tags/:tagId | Remove a tag from a lead |
A lead that was emailed or replied can be deleted too. Its replies go with it; the emails sent to it are kept (they count for mailbox daily limits, plan quota and bounce health).
Create/update leads
curl -X POST https://api.sendboxes.tech/leads \
-H "Authorization: Bearer sb_live_..." -H "Content-Type: application/json" \
-d '{
"leads": [
{ "email": "[email protected]", "firstName": "Jane", "companyDomain": "example.com" }
]
}'Lead fields: email (required), firstName, lastName, companyDomain, companyName,
phoneNumber, jobTitle, timezone, customFields (a flat string-keyed object — every key is
usable as a {{token}} in a sequence step).
An email already suppressed on your suppression list is skipped, not
rejected — the response reports how many were created, updated and suppressed.
The response also has leads: one { email, id, status } per lead (status is created or
updated), in the order you sent them. Match ids to your input by email. leadIds is the
same list of ids in the same order. Suppressed emails are listed in suppressedEmails and get no id.
Merge: if the email already exists, only the fields you send change; fields you leave out
keep their value. "" clears a field. customFields are merged key by key (send
{ "city": "NYC" } and the lead’s other custom fields stay). The same rules apply to
PATCH /leads/bulk.
timezone must be an IANA zone (e.g. America/New_York, see GET /timezones). On POST /leads
an unknown zone is skipped for that lead and listed in warnings; the lead is still saved. On
PATCH it is rejected with a 400.