Search contacts

Agent Skill

Automate this endpoint with an AI agent using the 2chat-contacts skill:

npx skills add 2ChatCo/agent-skills -s 2chat-contacts

This endpoint searches the contacts of your account by name or phone number. Results can be scoped to the contacts associated with one of your connected numbers.

To browse every contact without a search term use the List Contacts endpoint instead.

Endpoint

GET https://api.p.2chat.io/open/contacts/search

Authentication

Include your API key in the X-User-API-Key header. Learn more about authentication.

API cost

1API credit

Each call to this endpoint deducts 1 API credit from your plan's API credit pool.

Billing overview How API usage is billed

Parameters

These parameters are sent as query string parameters.

Field	Type	Required	Description
`query`	string	Yes	Text to look for. Matched against the contact's first name, last name and phone numbers. Examples: `Kate Smith`, `+12125550147`, `5550147`
`channel_uuid`	string	No	UUID of a connected number (`WPN...`). Only contacts associated with that number are returned. The number must belong to your account
`results_per_page`	integer	No	Contacts returned per page, between `1` and `50`. Defaults to `10`
`page_number`	integer	No	Zero-based page to return. Defaults to `0`

How matching works

Names are matched by prefix and ignore accents, so jose finds José Pérez. When the query has several words, every word must match some part of the name, in any order. Only the last word is treated as a prefix: Kate Sm finds Kate Smith, while Ka Smith does not.
Phone numbers are matched on digits only, so +1 (212) 555-0147, 12125550147 and 2125550147 are all accepted. At least five digits are needed. A complete, valid international number must match a phone number exactly; a shorter run of digits matches any phone number that contains those digits in that order.
A contact is returned when either the name or a phone number matches.
Results are served from the search index. A contact that was created or updated a few seconds ago may not appear yet.

Invocation

cURL
Python
JavaScript
PHP

curl --location 'https://api.p.2chat.io/open/contacts/search?query=kate&results_per_page=10&page_number=0' \
--header 'X-User-API-Key: your_api_key_here'

import requests

url = "https://api.p.2chat.io/open/contacts/search"
headers = {
    "X-User-API-Key": "your_api_key_here"
}
params = {
    "query":            "kate",
    "results_per_page": 10,
    "page_number":      0
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const axios = require('axios');

const response = await axios.get('https://api.p.2chat.io/open/contacts/search', {
    params: {
        query: 'kate',
        results_per_page: 10,
        page_number: 0
    },
    headers: {
        'X-User-API-Key': 'your_api_key_here'
    }
});

console.log(response.data);

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.p.2chat.io/open/contacts/search?' . http_build_query([
      'query'            => 'kate',
      'results_per_page' => 10,
      'page_number'      => 0
  ]),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'X-User-API-Key: your_api_key_here'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response

Success (HTTP 200 OK)

{
    "success": true,
    "page": 0,
    "count": 2,
    "contacts": [
        {
            "uuid": "CON8c1f4e2a-7b3d-4f0e-9a61-2d5c8e7f1b93",
            "first_name": "Kate",
            "last_name": "Smith",
            "name": "Kate Smith",
            "channel_uuid": "WPN3a9e7c15-2f84-4b6d-8e01-c7d2f9a4b5e6",
            "profile_pic_url": "https://2chat-user-data.s3.amazonaws.com/...",
            "last_updated": "2026-10-28T14:02:11Z",
            "details": [
                {
                    "id": 48213,
                    "type": "WAPH",
                    "value": "+12125550147"
                },
                {
                    "id": 48214,
                    "type": "E",
                    "value": "kate.smith@example.com"
                }
            ]
        },
        {
            "uuid": "CONd27b0a95-41c6-4e8f-b3a2-6f1e9c0d7a48",
            "first_name": "Katerina",
            "last_name": null,
            "name": "Katerina",
            "channel_uuid": null,
            "profile_pic_url": null,
            "last_updated": "2026-09-12T09:45:30Z",
            "details": [
                {
                    "id": 51907,
                    "type": "WAPH",
                    "value": "+5491155550123"
                }
            ]
        }
    ]
}

Field	Description
`success`	`true` when the request was successful
`page`	The zero-based page returned, echoing `page_number`
`count`	Total number of contacts matching the query across all pages. Use it with `results_per_page` to know how many pages there are
`contacts`	The contacts on this page
`contacts[].uuid`	Contact UUID. Use it with the Get, Update and Delete endpoints
`contacts[].first_name`, `contacts[].last_name`	The contact's name. `last_name` is `null` when not set
`contacts[].name`	First and last name joined, for display
`contacts[].channel_uuid`	UUID of the connected number the contact is associated with, or `null`
`contacts[].profile_pic_url`	URL of the contact's profile picture, or `null`
`contacts[].last_updated`	When the contact was last modified, in UTC
`contacts[].details`	Contact details: phone numbers and emails. `type` is `WAPH` for a WhatsApp phone number, `PH` for a plain phone number and `E` for an email address

Error

{
    "error": true,
    "error_message": "Payload is invalid: results_per_page needs to be between 1 and 50"
}

Field	Description
`error`	`true` when the request failed
`error_message`	A description of what went wrong

HTTP status	When
`400`	`results_per_page` is outside `1`–`50`, or `channel_uuid` is not a valid connected number UUID
`404`	`channel_uuid` does not exist on your account
`401`	The API key is missing or invalid

Search contacts

Endpoint​

Authentication​

API cost​

Parameters​

How matching works​

Invocation​

Response​

Success (HTTP 200 OK)​

Error​