Contacts

Read and feed your CRM from your tools: website forms, point-of-sale software, ERP… Contacts created here appear in Contacts.

List contacts

curl -X POST https://api.whatixo.com/api/whatsapp/contacts \
  -H "x-api-key: $WHATIXO_API_KEY" -H "Content-Type: application/json" \
  -d '{"tag":"vip","limit":100,"offset":0}'

// Walk the whole CRM, page by page
let offset = 0, page;
do {
  page = await whatixo('/whatsapp/contacts', { limit: 500, offset });
  for (const c of page.contacts) console.log(c.phone, c.name, c.tags);
  offset += page.count;
} while (page.hasMore);

offset = 0
while True:
    page = whatixo("/whatsapp/contacts", {"limit": 500, "offset": offset})
    for c in page["contacts"]:
        print(c["phone"], c.get("name"), c.get("tags"))
    offset += page["count"]
    if not page.get("hasMore"):
        break

{
  "success": true,
  "count": 2,
  "total": 214,
  "offset": 0,
  "hasMore": true,
  "contacts": [
    {
      "id": "c5f1…",
      "phone": "243812345601",
      "name": "Aline Mukendi",
      "tags": "customers,vip",
      "attributes": { "city": "Kinshasa" },
      "leadTemperature": "HOT",
      "messagesReceived": 12,
      "messagesRead": 10,
      "linksClicked": 3,
      "lastActivityAt": "2026-11-03T16:30:00.000Z",
      "createdAt": "2026-10-02T09:12:00.000Z"
    }
  ]
}

total, offset and hasMore are only present when you pass limit.

Read a contact

curl -X POST https://api.whatixo.com/api/whatsapp/contacts/info \
  -H "x-api-key: $WHATIXO_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"243812345601"}'

Response: {"success":true,"contact":{…}}, or 404 if the contact doesn’t exist.

Create or update a contact

If a contact with this number exists, it is updated; otherwise it is created. Ideal for syncing a form or a store.

curl -X POST https://api.whatixo.com/api/whatsapp/contacts/upsert \
  -H "x-api-key: $WHATIXO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "phone": "243812345601",
    "name": "Aline Mukendi",
    "tags": ["customers", "newsletter"],
    "attributes": { "city": "Kinshasa", "source": "website" }
  }'

// Example: your website's contact form
whatixo('/whatsapp/contacts/upsert', [
  'phone'      => $_POST['phone'],
  'name'       => $_POST['name'],
  'tags'       => ['leads', 'website'],
  'attributes' => ['message' => $_POST['message']],
]);

whatixo("/whatsapp/contacts/upsert", {
    "phone": "243812345601",
    "name": "Aline Mukendi",
    "tags": ["customers", "newsletter"],
    "attributes": {"city": "Kinshasa"},
})

Response: {"success":true,"contact":{…}}. If your plan’s contact limit is reached: 402 {"code":"PLAN_LIMIT","feature":"crm"}.

Check numbers

Tells you whether numbers have a WhatsApp account, before you send.

{ "deviceId": "8f2c1a7e-4b9d-4e21-9a6f-3c5d7e1b2a90", "phones": ["243812345601", "243000000000"] }

{
  "success": true,
  "results": [
    { "phone": "243812345601", "exists": true, "jid": "243812345601@s.whatsapp.net" },
    { "phone": "243000000000", "exists": false }
  ]
}

Profile picture

{ "deviceId": "8f2c1a7e-4b9d-4e21-9a6f-3c5d7e1b2a90", "phone": "243812345601" }

{ "success": true, "pictureUrl": "https://pps.whatsapp.net/v/t61…" }

If the contact has no picture or hides it, the API returns 500 with an explicit message. The returned URL is temporary: download the image if you need to keep it.