Skip to content

Contacts

Contacts are the people you message — with tags, lists, custom attributes and a recorded opt-in state.

Endpoints

The contact object

JSON
{
  "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

Body parameters
  • phonestringrequired
    Phone with country code. Normalised and used for deduplication: creating a second contact with the same phone returns 409 conflict — use PATCH to update.
  • namestringoptional
    Display name.
  • emailstringoptional
    Email address.
  • countrystringoptional
    ISO country code, e.g. IN.
  • languagestringoptional
    Preferred language code.
  • attributesobjectoptional
    Values for custom attributes defined in your organization.
  • tagsstring[]optional
    Tag names; missing tags are created.
  • opt_inenumoptional
    opted_in or opted_out. Changes are recorded in the consent history.
  • blockedbooleanoptional
    Blocked contacts can't be messaged.
POST /v1/contacts
{
  "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).

Deleting contacts
Contacts can be deleted only from the dashboard, by a signed-in person with the right role. API keys can't delete contacts.

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

POST /v1/contacts/bulk → { affected }
{
  "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.

POST /v1/contacts/import
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…" }
Form fieldDescription
fileThe CSV file (Excel files aren't accepted — export as CSV first)
mappingJSON object of CSV column → target. Targets: phone (required), name, email, tags (a column of tag names split on , ; or |), attribute.<key>
tagsJSON array of tag ids to add to every imported contact
list_idAdd every imported contact to this list
opt_inopted_in or opted_out for every imported contact

Job status

Poll GET /v1/jobs/{id}. Status is queued, running, completed or failed; job details are kept for 7 days.

JSON
{
  "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.

Something unclear or missing on this page? Tell us at contact@swastik.ai