GET /contacts

List all contacts belonging to the account. A filter can be specified in order to get more specific results.

Optional Parameters

Parameter	Type	Description
page	Integer	The page of contacts. If not specified it will default to page 1. Pages beyond 500 are not available — use cursor pagination instead.
after	string	Opaque cursor taken from meta.next of a previous response. Returns the batch of contacts that follows it. See Cursor pagination.
source	Source	The integration type (e.g. whatsapp)
tags	string[]	The matching tags, comma-separated (e.g. sales,lead). Tags are case-insentive.
team_uuid	string	The uuid of the team.
include_field_types	boolean	When true, the response includes customFieldsMetadata with value, type and options for each custom field.

Cursor pagination

Page-based pagination stops at page 500 (10,000 contacts): requests beyond that limit return a 400 Bad Request error with the message Pagination limit exceeded. To walk the complete contact list, use cursor pagination instead:

1. Make a request as usual: every response includes an opaque token in meta.next.
2. Pass the token back through the after parameter to fetch the next batch of contacts.
3. Keep following meta.next until it comes back null — that marks the last batch.

curl -X GET "https://api.callbell.eu/v1/contacts?after=eyJ0cyI6MTc1NDM4NDQwMDAwMCwiaWQiOjEyMzQ1fQ" \
    -H "Authorization: Bearer test_gshuPaZoeEG6ovbc8M79w0QyM" \
    -H "Content-Type: application/json"

A few things to keep in mind:

• Treat the token as opaque and send it back unchanged. A malformed token returns a 400 Bad Request error with the message Invalid pagination cursor.
• The page parameter is ignored when after is present.
• Filters (source, tags, team_uuid) are not encoded in the token — pass the same filters along with after on every request.
• Contacts are returned in the same order as page-based requests (most recent conversation first). Contacts created after the walk started are not included.

Example Request

cURL

curl -X GET "https://api.callbell.eu/v1/contacts" \
    -H "Authorization: Bearer test_gshuPaZoeEG6ovbc8M79w0QyM" \
    -H "Content-Type: application/json"

Node

import axios from 'axios';

const response = await axios.get('https://api.callbell.eu/v1/contacts', {
  headers: {
    'Authorization': 'Bearer test_gshuPaZoeEG6ovbc8M79w0QyM',
    'Content-Type': 'application/json'
  }
});

Ruby

require 'net/http'

uri = URI('https://api.callbell.eu/v1/contacts')
req = Net::HTTP::Get.new(uri)
req.content_type = 'application/json'
req['Authorization'] = 'Bearer test_gshuPaZoeEG6ovbc8M79w0QyM'

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

Go

package main

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

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "https://api.callbell.eu/v1/contacts", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("Authorization", "Bearer test_gshuPaZoeEG6ovbc8M79w0QyM")
    req.Header.Set("Content-Type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    bodyText, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.callbell.eu/v1/contacts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer test_gshuPaZoeEG6ovbc8M79w0QyM',
    'Content-Type: application/json',
]);

$response = curl_exec($ch);

curl_close($ch);

Python

import requests

headers = {
    'Authorization': 'Bearer test_gshuPaZoeEG6ovbc8M79w0QyM',
    'Content-Type': 'application/json',
}

response = requests.get('https://api.callbell.eu/v1/contacts', headers=headers)

C#

using System.Net.Http;
using System.Net.Http.Headers;

HttpClient client = new HttpClient();

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, "https://api.callbell.eu/v1/contacts");

request.Headers.Add("Authorization", "Bearer test_gshuPaZoeEG6ovbc8M79w0QyM");

request.Content = new StringContent("");
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();

Java

import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

class Main {

    public static void main(String[] args) throws IOException {
        URL url = new URL("https://api.callbell.eu/v1/contacts");
        HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
        httpConn.setRequestMethod("GET");

        httpConn.setRequestProperty("Authorization", "Bearer test_gshuPaZoeEG6ovbc8M79w0QyM");
        httpConn.setRequestProperty("Content-Type", "application/json");

        InputStream responseStream = httpConn.getResponseCode() / 100 == 2
                ? httpConn.getInputStream()
                : httpConn.getErrorStream();
        Scanner s = new Scanner(responseStream).useDelimiter("\\A");
        String response = s.hasNext() ? s.next() : "";
        System.out.println(response);
    }
}

Rust

extern crate reqwest;
use reqwest::header;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut headers = header::HeaderMap::new();
    headers.insert("Authorization", "Bearer test_gshuPaZoeEG6ovbc8M79w0QyM".parse().unwrap());
    headers.insert("Content-Type", "application/json".parse().unwrap());

    let client = reqwest::blocking::Client::builder()
        .redirect(reqwest::redirect::Policy::none())
        .build()
        .unwrap();
    let res = client.get("https://api.callbell.eu/v1/contacts")
        .headers(headers)
        .send()?
        .text()?;
    println!("{}", res);

    Ok(())
}

Response

Parameter	Type	Description
contacts	Contact[]	A list of contacts.
meta	object	Pagination metadata: page and pages for page-based requests, plus next, the cursor pointing to the next batch (null on the last batch).

Example Response

response.json

{
  "contacts": [
    {
      "uuid": "414a6d692bd645ed803f2e7ce360d4c8",
      "name": "John Doe",
      "phoneNumber": "+123 456 789",
      "avatarUrl": null,
      "createdAt": "2020-11-13T21:08:53Z",
      "source": "whatsapp",
      "href": "https://dash.callbell.eu/contacts/414a6d692bd645ed803f2e7ce360d4c8",
      "conversationHref": "https://dash.callbell.eu/chat/f3670b13446b412796238b1cd78899f9",
      "assignedUser": "john.doe@email.com",
      "tags": [
        "sales",
        "lead"
      ],
      "customFields":{
        "Stripe link": "https://stripe.com/contacts/cus1234567",
        "Billing Address": "3 Abbey Rd, London"
      }
    },
    ...
    {
      "uuid": "ff8bec9363bc4c29b8b044eabf2afebd",
      "name": "Mario Rossi",
      "phoneNumber": "+33 11 22 33 44",
      "avatarUrl": null,
      "createdAt": "2021-02-24T20:33:06Z",
      "source": "whatsapp",
      "href": "https://dash.callbell.eu/contacts/ff8bec9363bc4c29b8b044eabf2afebd",
      "conversationHref": "https://dash.callbell.eu/chat/f3670b13446b412796238b1cd78899f9",
      "assignedUser": null,
      "tags": [
        "sales",
        "lead",
        "hot"
      ],
      "customFields":{
        "Stripe link": "https://stripe.com/contacts/cus124124153"
      }
    }
  ],
  "meta": {
    "page": 1,
    "pages": 42,
    "next": "eyJ0cyI6MTc1NDM4NDQwMDAwMCwiaWQiOjEyMzQ1fQ"
  }
}

Example Response (with include_field_types=true)

response.json

{
  "contacts": [
    {
      "uuid": "414a6d692bd645ed803f2e7ce360d4c8",
      "name": "John Doe",
      "customFields": {
        "Address": "Oxford Street 123",
        "Join Date": "2024-01-15",
        "Preferences": "[\"Newsletter\", \"Promotions\"]"
      },
      "customFieldsMetadata": {
        "Address": { "value": "Oxford Street 123", "type": "text" },
        "Join Date": { "value": "2024-01-15", "type": "date" },
        "Preferences": { "value": ["Newsletter", "Promotions"], "type": "checkbox", "options": ["Newsletter", "Promotions", "Updates"] }
      }
    }
  ]
}