Skip to main content
GET
/
api
/
chat
/
contacts
/
:instance
List contacts
curl --request GET \
  --url https://api.example.com/api/chat/contacts/:instance
Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: yes

​
Description

Returns the list of contacts synced in the WhatsMeow ContactStore, these are the contacts coming from the main phone’s address book: name, push name, business name, and redacted phone number. If ?number= is provided, returns a single contact. If the number is not in the address book, the response is still 200 OK with contact.found = false.
Read-only operation against the local store, does not generate any WhatsApp traffic.

​
Examples

​
List all

Without query params, returns every contact synced in the instance’s local ContactStore, with total indicating the size of the list. 
curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name" \
  -H "token: $Token_Instance"

​
Specific number

Filters by ?number=5511999999999 (international phone). Returns the single contact object, with found=false when the number is not in the synced address book. 
curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name?number=5511999999999" \
  -H "token: $Token_Instance"

​
Full JID

Accepts the entire JID in ?number=5511999999999@s.whatsapp.net when you already have the full identifier (from a webhook or another API response), avoiding manually building the suffix. 
curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name?number=5511999999999@s.whatsapp.net" \
  -H "token: $Token_Instance"

​
Success response

Without ?number, returns contacts (array) with every contact synced from the address book + total. With ?number=..., returns only contact (a single object). Each item carries jid, lid (when applicable), the available names (first_name, full_name, push_name, business_name), and redacted_phone for cases where we only know the LID. The found field indicates whether the entry came from the store.
200 OK
{
  "success": true,
  "message": "Contacts retrieved successfully",
  "contacts": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "lid": "",
      "first_name": "John",
      "full_name": "John Smith",
      "push_name": "John",
      "business_name": "",
      "redacted_phone": "+55 11 ..... 9999",
      "found": true
    },
    {
      "jid": "5511888888888@s.whatsapp.net",
      "full_name": "Mary",
      "push_name": "Mary S.",
      "found": true
    }
  ],
  "total": 42
}

​
Path parameters

​
instance
string
required
Instance name (e.g., $Instance_Name).

​
Headers

NameRequiredExampleDescription
tokenyes (or Authorization)a1b2c3d4-...TokenAccount or TokenInstance.

​
Query params

​
number
string
International phone (5511999999999) or JID (5511999999999@s.whatsapp.net, ...@lid). If provided, returns only this contact.

​
Notes and gotchas

  • found=false with empty push_name and empty redacted_phone usually means the number does not have WhatsApp or never exchanged messages with you.
  • business_name is only filled for verified WhatsApp Business accounts.
  • Operations involving more than a thousand contacts may take a few seconds because of the context.WithTimeout(30s) applied to GetAllContacts.

​
Error responses

HTTPerror.messageWhen it happens
400Instance name is requiredEmpty :instance.
401Invalid tokenSee Authentication.
404Instance not foundThe instance does not exist on the account.
500WhatsApp client not found for instanceClient deallocated.
500WhatsApp client is not connectedDisconnected instance.
500contact store not available (use a store that implements ContactStore, e.g. sqlstore)Store not supported.
500invalid number: <...>Malformed ?number=.
500failed to get contacts: <...> / failed to get contact: <...>Internal WhatsMeow error.
Error 400
{
  "success": false,
  "error": { "message": "Instance name is required" }
}