List contacts

List the contacts of a number, with filters and cursor pagination. Items come from the most recently updated to the oldest.

Each contact belongs to a number: {ref} is main (main number), the alias of an extra number or its id (num_…), and the same phone reached by two different numbers corresponds to two distinct contacts.

Endpoint

GET /v1/contacts?limit=20&cursor=<opaque>

For extra numbers: GET /v1/numbers/{ref}/contacts?limit=20&cursor=<opaque>

Using extra numbers?

To list the contacts of an extra number, use /v1/numbers/{ref}/contacts, where {ref} is the alias of your extra number (or its id, num_…). Learn more.

Required scope: contacts:read.

Query parameters

Parameter	Type	Description
limit	int	1 to 200 (default 50)
cursor	string	Opaque token returned in cursor
phone	string	Exact match on an E.164 phone number. In the URL, write the + as %2B (phone=%2B5511988887777) or send digits only (phone=5511988887777): a bare + turns into a space and the filter finds nothing
name	string	Partial match on the contact name
source	enum	inbound | outbound | self | mention: mention is a contact first seen because it was mentioned in a message; contacts created by a mention do not take a slot of the contact quota
contacted_in_cycle	bool	Returns only the contacts you talked to through Turbo Notify within the current billing cycle (new or returning). A send that did not reach WhatsApp does not count

Request example

cURL

curl -X GET "https://api.turbonotify.com/v1/contacts?limit=20" \
  -H "Authorization: Bearer YOUR_KEY"

Only the contacts that took a slot of the current cycle’s quota:

curl -X GET "https://api.turbonotify.com/v1/contacts?contacted_in_cycle=true" \
  -H "Authorization: Bearer YOUR_KEY"

Node

const res = await fetch("https://api.turbonotify.com/v1/contacts?limit=20", {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data, cursor, has_more } = await res.json();

Python

import httpx
r = httpx.get(
    "https://api.turbonotify.com/v1/contacts",
    params={"limit": 20},
    headers={"Authorization": "Bearer YOUR_KEY"},
)
data = r.json()

Go

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest(
        "GET",
        "https://api.turbonotify.com/v1/contacts?limit=20",
        nil,
    )
    req.Header.Set("Authorization", "Bearer YOUR_KEY")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

PHP

<?php
$url = 'https://api.turbonotify.com/v1/contacts?limit=20';

$options = [
    'http' => [
        'header' => ['Authorization: Bearer YOUR_KEY'],
        'method' => 'GET'
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
var_dump($response['data']);
?>

C#

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_KEY");

var response = await client.GetAsync(
    "https://api.turbonotify.com/v1/contacts?limit=20"
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Java

import java.net.http.*;
import java.net.URI;

public class ListContacts {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/contacts?limit=20"))
            .header("Authorization", "Bearer YOUR_KEY")
            .GET()
            .build();

        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Response (200)

HTTP status: 200

{
  "data": [
    {
      "id": "ct_a1b2c3d4e5f6789012345678901234ab",
      "number_alias": "main",
      "phone_number": "+5511988887777",
      "name": "João Silva",
      "is_self": false,
      "first_messaged_at": "2026-05-10T13:25:00Z",
      "last_interaction_at": "2026-05-10T13:42:00Z",
      "verified_on_whatsapp_at": "2026-05-10T13:25:00Z",
      "picture": {
        "kind": "unavailable",
        "reason": "peer_has_none"
      },
      "refresh": null,
      "created_at": "2026-05-10T13:25:00Z",
      "updated_at": "2026-05-10T13:42:00Z"
    }
  ],
  "cursor": "eyJpZCI6ImN0XzAxIn0=",
  "has_more": true
}

Each item is the same object returned by Detail, which explains each field. The phone_number is the full E.164 (unmasked). The contact has its own dates (created_at, updated_at, first_messaged_at and the others), which do not repeat the dates of an event.

See also: Detail · Errors.