List Contacts

Retrieve contacts from your WhatsApp instance with filtering and pagination.

POST /chat/findContacts/:instanceName

cURL

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()

200 Success

{
  "contacts": [
    {
      "id": "contact_123",
      "remoteJid": "[e-mail]",
      "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": "[e-mail]",
      "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.

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.

Show properties

where.remoteJid · string

Filter by remote JID (WhatsApp ID).

where.pushName · string

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

where.owner · string

Filter by instance owner.

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.

Show properties

sort.field · string

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

sort.order · string

Sort order: “asc” or “desc”.

Response

contacts · array

Array of contact objects.

Show properties

id · string

Unique contact identifier.

remoteJid · string

WhatsApp JID of the contact.

pushName · string

Contact’s display name.

owner · string

Instance owner.

profilePictureUrl · string

URL of the contact’s profile picture.

createdAt · string

ISO 8601 timestamp of when the contact was first saved.

updatedAt · string

ISO 8601 timestamp of last update.

total · number

Total number of contacts matching the query.

cURL

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()

200 Success

{
  "contacts": [
    {
      "id": "contact_123",
      "remoteJid": "[e-mail]",
      "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": "[e-mail]",
      "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.