Skip to main content
POST
/
chat
/
findContacts
/
:instanceName
curl --request POST \
  --url https://api.example.com/chat/findContacts/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "limit": 50,
    "offset": 0,
    "sort": {
      "field": "pushName",
      "order": "asc"
    }
  }'

{
  "contacts": [
    {
      "id": "contact_123",
      "remoteJid": "[email protected]",
      "pushName": "John Doe",
      "owner": "my-instance",
      "profilePictureUrl": "https://example.com/profile-john.jpg",
      "createdAt": "2024-03-04T10:30:00.000Z",
      "updatedAt": "2024-03-04T12:45:00.000Z"
    },
    {
      "id": "contact_456",
      "remoteJid": "[email protected]",
      "pushName": "Jane Smith",
      "owner": "my-instance",
      "profilePictureUrl": "https://example.com/profile-jane.jpg",
      "createdAt": "2024-03-03T15:20:00.000Z",
      "updatedAt": "2024-03-04T11:30:00.000Z"
    }
  ],
  "total": 2
}

​
Overview

You can fetch all contacts from your WhatsApp instance. This endpoint supports advanced filtering and pagination to help you find specific contacts efficiently.
Contacts are automatically synced from your WhatsApp instance. This includes both saved contacts and users you’ve chatted with.

​
Authentication

This endpoint requires authentication via the apikey header.
​
header.apikey
string
required
Your Evolution API key for authentication.

​
Path Parameters

​
path.instanceName
string
required
The name of your WhatsApp instance.

​
Request Body

The request body accepts a query object for filtering and pagination:
​
where
object
Filter criteria for contacts.
​
limit
number
default:"20"
Maximum number of contacts to return.
​
offset
number
default:"0"
Number of contacts to skip (for pagination).
​
sort
object
Sorting configuration.

​
Response

​
contacts
array
Array of contact objects.
​
total
number
Total number of contacts matching the query.
curl --request POST \
  --url https://api.example.com/chat/findContacts/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "limit": 50,
    "offset": 0,
    "sort": {
      "field": "pushName",
      "order": "asc"
    }
  }'

{
  "contacts": [
    {
      "id": "contact_123",
      "remoteJid": "[email protected]",
      "pushName": "John Doe",
      "owner": "my-instance",
      "profilePictureUrl": "https://example.com/profile-john.jpg",
      "createdAt": "2024-03-04T10:30:00.000Z",
      "updatedAt": "2024-03-04T12:45:00.000Z"
    },
    {
      "id": "contact_456",
      "remoteJid": "[email protected]",
      "pushName": "Jane Smith",
      "owner": "my-instance",
      "profilePictureUrl": "https://example.com/profile-jane.jpg",
      "createdAt": "2024-03-03T15:20:00.000Z",
      "updatedAt": "2024-03-04T11:30:00.000Z"
    }
  ],
  "total": 2
}

​
Usage Notes

Use pagination with limit and offset to efficiently load large contact lists.
Contacts are automatically updated when you receive messages or interact with users on WhatsApp.
The pushName field reflects the name set by the contact themselves, not your saved contact name.

Build docs developers (and LLMs) love

Get started for freeTalk to us