List Contacts

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"
    }
  }'

curl --request POST \
  --url https://api.example.com/chat/findContacts/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "where": {
      "pushName": "John"
    },
    "limit": 20
  }'

const response = await fetch(
  'https://api.example.com/chat/findContacts/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      limit: 50,
      offset: 0,
      sort: {
        field: 'pushName',
        order: 'asc'
      }
    })
  }
);

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/chat/findContacts/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'limit': 50,
        'offset': 0,
        'sort': {
            'field': 'pushName',
            'order': 'asc'
        }
    }
)

data = response.json()

{
  "contacts": [
    {
      "id": "contact_123",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "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": "5511888888888@s.whatsapp.net",
      "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
}

{
  "error": "Invalid query parameters",
  "message": "Limit must be a positive number"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

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.

string

required

Your Evolution API key for authentication.

Path Parameters

string

required

The name of your WhatsApp instance.

Request Body

The request body accepts a query object for filtering and pagination:

object

Filter criteria for contacts.

Show properties

string

Filter by remote JID (WhatsApp ID).

string

Filter by contact’s push name (display name).

string

Filter by instance owner.

number

default:"20"

Maximum number of contacts to return.

number

default:"0"

Number of contacts to skip (for pagination).

object

Sorting configuration.

Show properties

string

Field name to sort by (e.g., “pushName”, “createdAt”).

string

Sort order: “asc” or “desc”.

Response

array

Array of contact objects.

Show properties

string

Unique contact identifier.

string

WhatsApp JID of the contact.

string

Contact’s display name.

string

Instance owner.

string

URL of the contact’s profile picture.

string

ISO 8601 timestamp of when the contact was first saved.

string

ISO 8601 timestamp of last update.

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"
    }
  }'

curl --request POST \
  --url https://api.example.com/chat/findContacts/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "where": {
      "pushName": "John"
    },
    "limit": 20
  }'

const response = await fetch(
  'https://api.example.com/chat/findContacts/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      limit: 50,
      offset: 0,
      sort: {
        field: 'pushName',
        order: 'asc'
      }
    })
  }
);

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/chat/findContacts/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'limit': 50,
        'offset': 0,
        'sort': {
            'field': 'pushName',
            'order': 'asc'
        }
    }
)

data = response.json()

{
  "contacts": [
    {
      "id": "contact_123",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "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": "5511888888888@s.whatsapp.net",
      "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
}

{
  "error": "Invalid query parameters",
  "message": "Limit must be a positive number"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

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.

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"
    }
  }'

curl --request POST \
  --url https://api.example.com/chat/findContacts/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "where": {
      "pushName": "John"
    },
    "limit": 20
  }'

const response = await fetch(
  'https://api.example.com/chat/findContacts/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      limit: 50,
      offset: 0,
      sort: {
        field: 'pushName',
        order: 'asc'
      }
    })
  }
);

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/chat/findContacts/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'limit': 50,
        'offset': 0,
        'sort': {
            'field': 'pushName',
            'order': 'asc'
        }
    }
)

data = response.json()

{
  "contacts": [
    {
      "id": "contact_123",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "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": "5511888888888@s.whatsapp.net",
      "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
}

{
  "error": "Invalid query parameters",
  "message": "Limit must be a positive number"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Overview

Instance Management

Messaging

Chats

Groups

Contacts

Labels

Settings

Proxy

Overview

Authentication

Path Parameters

Request Body

Response

Usage Notes

​Overview

​Authentication

​Path Parameters

​Request Body

​Response

​Usage Notes

Overview

Authentication

Path Parameters

Request Body

Response

Usage Notes