List contacts

cURL

curl --request GET \
  --url https://api.teamfollowup.ai/api/contacts \
  --header 'Authorization: Bearer YOUR_API_KEY'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.teamfollowup.ai/api/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.teamfollowup.ai/api/contacts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "64f2a8c8a2b3c4d5e6f7a8b9",
        "_id": "64f2a8c8a2b3c4d5e6f7a8b9",
        "phoneNumber": "+14155551234",
        "leadName": "Alex Morgan",
        "projectName": "Acme Clinic",
        "dateAdded": "2026-07-08T16:00:00.000Z",
        "callCount": 3,
        "contactId": "contact_123",
        "locationId": "loc_9f7a123",
        "crm": "ghl",
        "leadId": null,
        "kommoSubdomain": null,
        "ghlWhitelabelDomain": null,
        "isInternal": false,
        "nextScheduledCall": {
          "nextCallTime": "2026-07-09T14:30:00.000Z",
          "cadenceStep": 1
        },
        "disposition": {
          "type": "appointment",
          "label": "Appointment",
          "color": "green"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "totalPages": 1
    }
  }
}

{
  "success": false,
  "error": "projectName is required"
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "Access denied to this project"
}

{
  "success": false,
  "error": "TooManyRequests"
}

{
  "success": false,
  "error": "Unexpected server error."
}

GET

api

contacts

cURL

curl --request GET \
  --url https://api.teamfollowup.ai/api/contacts \
  --header 'Authorization: Bearer YOUR_API_KEY'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.teamfollowup.ai/api/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.teamfollowup.ai/api/contacts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "64f2a8c8a2b3c4d5e6f7a8b9",
        "_id": "64f2a8c8a2b3c4d5e6f7a8b9",
        "phoneNumber": "+14155551234",
        "leadName": "Alex Morgan",
        "projectName": "Acme Clinic",
        "dateAdded": "2026-07-08T16:00:00.000Z",
        "callCount": 3,
        "contactId": "contact_123",
        "locationId": "loc_9f7a123",
        "crm": "ghl",
        "leadId": null,
        "kommoSubdomain": null,
        "ghlWhitelabelDomain": null,
        "isInternal": false,
        "nextScheduledCall": {
          "nextCallTime": "2026-07-09T14:30:00.000Z",
          "cadenceStep": 1
        },
        "disposition": {
          "type": "appointment",
          "label": "Appointment",
          "color": "green"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "totalPages": 1
    }
  }
}

{
  "success": false,
  "error": "projectName is required"
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "Access denied to this project"
}

{
  "success": false,
  "error": "TooManyRequests"
}

{
  "success": false,
  "error": "Unexpected server error."
}

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Query Parameters

projectName

string

Restrict results to one project visible to the caller.

locationId

string

Restrict results to one project by its stable location id. Preferred over projectName, which is not stable across renames.

campaignId

string

Restrict results to the leads one campaign dialled. Resolved against call records, so the count matches the campaign figures on the dashboard. Only V2 activity carries campaign attribution.

masterCampaignId

string

Restrict results to the leads an entire master campaign dialled, across every linked project the caller can see. A master campaign is fanned out into one child campaign per project, each with its own id, so filtering by a single campaignId returns one project's share of it. Mutually exclusive with campaignId: the two are contradictory scopes rather than narrowing ones, and sending both is a 400.

projects

string

Comma-separated project names for agency-level filtering.

string

Search by contact name, phone number, or contact id.

dateFromUTC

string<date-time>

Inclusive UTC lower bound for contact creation time.

dateToUTC

string<date-time>

Inclusive UTC upper bound for contact creation time.

disposition

enum<string>[]

Outcome filter. Send it repeated (disposition=appointment&disposition=callBack) or comma-joined (appointment,callBack) to match several.

Available options:

killSwitch,

callBack,

appointment,

liveTransfer,

failedTransfer,

tagged

internal

enum<string>

How to treat contacts marked as your own test leads. all (the default) lists them alongside everything else with isInternal set on each row, only narrows to just those, exclude hides them. They are listed by default because hiding them would leave no way to find one and undo the mark.

Available options:

all,

only,

exclude

page

integer

Page number, starting at 1.

Required range: x >= 1

limit

integer

Contacts per page.

Required range: 1 <= x <= 500

sortBy

enum<string>

Sort field.

Available options:

leadName,

phoneNumber,

projectName,

dateAdded,

callCount

sortOrder

enum<string>

Sort direction.

Available options:

asc,

desc

Response

Contacts page returned successfully.

success

boolean

required

data

object

required

Show child attributes

Agents

Skills & Tools

Campaigns

Campaign Workflows

Calls

Analytics

Projects

Power Dialer

Contacts

Phone Numbers

Voices

GHL

Authorizations

Query Parameters

Response