“API: contacts”

List contacts — GET /api/v1/contacts

Scope: contacts:read. Newest first, paginated.

{
  "data": [
    {
      "id": "…", "phone": "+14155550123", "name": "Jane Doe",
      "email": null, "company": "Acme", "avatar_url": null,
      "tags": [{ "id": "…", "name": "vip", "color": "#3b82f6" }],
      "created_at": "…", "updated_at": "…"
    }
  ],
  "meta": { "next_cursor": "…" }
}

Create a contact — POST /api/v1/contacts

Scope: contacts:write.

curl -X POST https://app.vatli.co/api/v1/contacts \
  -H "Authorization: Bearer vatli_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155550123", "name": "Jane Doe", "email": "jane@example.com", "company": "Acme", "tags": ["Website lead", "Patna"] }'

• phone (E.164) is required; everything else is optional.
• tags is a list of tag names; missing tags are created.
• Find-or-create: if the number already exists you get 200 with the existing contact; a new contact returns 201.

Read one — GET /api/v1/contacts/{id}

Scope: contacts:read. A contact from another workspace returns 404.

Update — PATCH /api/v1/contacts/{id}

Scope: contacts:write. Only the fields you send change (name, email, company). Send tags to replace the contact’s tags with that list.

{ "company": "Acme Pvt Ltd", "tags": ["Customer"] }