Docs

Contacts

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

GET/v1/contacts— ?q&tag&list&segment&opt_in&cursor&limit

POST/v1/contacts

GET/v1/contacts/{id}

PATCH/v1/contacts/{id}

DELETE/v1/contacts/{id}

POST/v1/contacts/{id}/tags— { tag_ids: [...] }

POST/v1/contacts/import— CSV import job

GET/v1/contacts/export— CSV download

The contact object

json

{
  "id": "b1e7…",
  "phone": "+919812345678",
  "bsuid": "IN.1234567890",
  "username": null,
  "name": "Ananya Rao",
  "profile_name": "Ananya",
  "email": "ananya@example.com",
  "country": "IN",
  "attributes": { "city": "Bengaluru", "tier": "gold", "last_order_value": 2499 },
  "opt_in": "opted_in",
  "tags": [{ "id": "7f…", "name": "VIP", "color": "#0F9D6E" }],
  "last_inbound_at": "2026-11-11T10:40:12Z",
  "last_outbound_at": "2026-11-11T10:42:00Z",
  "created_at": "2026-08-02T06:11:45Z"
}

Create or update

Parameters

phonestringoptional
E.164 phone number. Normalised and used for deduplication.
namestringoptional
Display name.
emailstringoptional
Email address.
attributesobjectoptional
Values for custom attributes defined in your organization (text, number, date, boolean, enum).
tagsstring[]optional
Tag names; missing tags are created.
opt_inenumoptional
opted_in or opted_out. Changes are recorded in the consent ledger.

POST /v1/contacts

{
  "phone": "+919812345678",
  "name": "Ananya Rao",
  "attributes": { "city": "Bengaluru" },
  "tags": ["VIP", "Diwali-2026"],
  "opt_in": "opted_in"
}

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.

Importing

Upload a CSV with a column mapping. The import runs as a background job; poll GET /v1/jobs/{id} for progress.

POST /v1/contacts/import

curl https://api.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"}' \
  -F 'tags=["imported"]' \
  -F "opt_in=opted_in"

# → { "job_id": "a3f…" }

Job status

json

{ "id": "a3f…", "kind": "contacts.import", "status": "completed", "progress": 10000, "total": 10000,
  "result": { "created": 9120, "updated": 812, "skipped": 68, "errors_url": "…" } }

Tags, lists, segments

/v1/tags — { name, color }
/v1/lists — static lists; add members with POST /v1/lists/{id}/members
/v1/segments — dynamic rules evaluated at send time; preview counts with POST /v1/segments/preview

Segment rules

{
  "name": "Engaged VIPs in Bengaluru",
  "rules": {
    "op": "and",
    "conditions": [
      { "field": "tag", "operator": "eq", "value": "VIP" },
      { "field": "attribute.city", "operator": "eq", "value": "Bengaluru" },
      { "field": "last_inbound_at", "operator": "within_days", "value": 30 }
    ]
  }
}