Contacts
Contacts are the people you message — with tags, lists, custom attributes and a recorded opt-in state.
- GET
/v1/contacts?q, ?tag, ?list, ?segment, ?opt_in, ?cursor, ?limitcontacts:read - POST
/v1/contactsCreate a contactcontacts:write - GET
/v1/contacts/{id}contacts:read - PATCH
/v1/contacts/{id}Update fields, add tags, merge attributescontacts:write - POST
/v1/contacts/{id}/tags{ tag_ids: [...] }contacts:write - DELETE
/v1/contacts/{id}/tags/{tag_id}contacts:write - GET
/v1/contacts/{id}/timelineConsent changes, campaigns and conversationscontacts:read - GET
/v1/contacts/{id}/conversationscontacts:read - POST
/v1/contacts/bulkTag, list or opt in/out up to 5,000 contactscontacts:write - POST
/v1/contacts/importCSV import jobcontacts:import - GET
/v1/jobs/{id}Import job progress - GET
/v1/contacts/exportCSV download (same filters as the list)contacts:export
The contact object
{
"id": "b1e7…",
"phone": "14155550101",
"bsuid": "IN.1234567890",
"username": null,
"name": "Jane Doe",
"profile_name": "Jane",
"email": "ananya@example.com",
"country": "US",
"language": "en",
"attributes": { "city": "Bengaluru", "tier": "gold", "last_order_value": 2499 },
"opt_in": "opted_in",
"blocked": false,
"tags": [{ "id": "7f…", "name": "VIP", "color": "#0F9D6E" }],
"source": "api",
"last_inbound_at": "2026-11-11T10:40:12Z",
"last_outbound_at": "2026-11-11T10:42:00Z",
"created_at": "2026-08-02T06:11:45Z",
"updated_at": "2026-11-11T10:42:00Z"
}phone is stored as digits with the country code and no +. bsuid and username identify WhatsApp users who hide their number.
Create a contact
phonestringrequiredPhone with country code. Normalised and used for deduplication: creating a second contact with the same phone returns409 conflict— usePATCHto update.namestringoptionalDisplay name.emailstringoptionalEmail address.countrystringoptionalISO country code, e.g.IN.languagestringoptionalPreferred language code.attributesobjectoptionalValues for custom attributes defined in your organization.tagsstring[]optionalTag names; missing tags are created.opt_inenumoptionalopted_inoropted_out. Changes are recorded in the consent history.blockedbooleanoptionalBlocked contacts can't be messaged.
{
"phone": "+14155550101",
"name": "Jane Doe",
"attributes": { "city": "Bengaluru" },
"tags": ["VIP", "Diwali-2026"],
"opt_in": "opted_in"
}Update a contact
PATCH /v1/contacts/{id} takes the same fields. attributes are merged into the existing ones, and tags are added (use DELETE /v1/contacts/{id}/tags/{tag_id} to remove one).
Opt-in and opt-out
Marketing templates are never sent to opted-out contacts, even if they're in a campaign audience. Replies such as STOP or UNSUBSCRIBE opt a contact out automatically, and START or SUBSCRIBE opts them back in. Every change fires the contact.consent_changed webhook.
Bulk actions
{
"contact_ids": ["b1e7…", "c9a2…"],
"action": "add_tags",
"tag_ids": ["7f…"]
}Actions: add_tags, remove_tags (with tag_ids), add_to_list, remove_from_list (with list_id), opt_in, opt_out. Up to 5,000 contacts per call.
Importing
Upload a CSV (up to 50 MB, about a million rows) with a column mapping. Existing phones are updated: name and email are replaced if present, attributes are merged. The import runs as a background job.
curl https://engage.swastik.ai/v1/contacts/import \
-H "Authorization: Bearer $ENGAGE_API_KEY" \
-F "file=@customers.csv" \
-F 'mapping={"Mobile":"phone","Full name":"name","City":"attribute.city","Labels":"tags"}' \
-F 'tags=["7f3a…"]' \
-F "list_id=2c4e…" \
-F "opt_in=opted_in"
# → 202 { "job_id": "a3f…" }Job status
Poll GET /v1/jobs/{id}. Status is queued, running, completed or failed; job details are kept for 7 days.
{
"id": "a3f…",
"kind": "contact_import",
"status": "completed",
"progress": 10000,
"total": 10000,
"result": {
"total": 10000,
"imported": 9932,
"invalid": 41,
"duplicates_in_file": 27,
"errors": [{ "row": 118, "error": "Invalid phone '98123'" }]
}
}errors lists up to the first 100 rows that couldn't be imported.
Exporting
GET /v1/contacts/export returns a CSV file (up to 200,000 rows) and accepts the same filters as the list.