Get Contacts - CallKaro AI Docs

Get Contacts

curl --request GET \
  --url https://api.callkaro.ai/contact/get \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.callkaro.ai/contact/get', 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.callkaro.ai/contact/get",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$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.callkaro.ai/contact/get"

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

	req.Header.Add("X-API-KEY", "<api-key>")

	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.callkaro.ai/contact/get")

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

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

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

{
  "status": "done",
  "contacts": [
    {
      "to_number": "919876543210",
      "channels": [],
      "attributes": {
        "first_name": "Rahul",
        "city": "Pune"
      },
      "created_at": "2026-10-27 11:42:05.118",
      "updated_at": "2026-10-27 11:42:05.118",
      "last_message_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1
  }
}

{
  "status": "error",
  "message": "page_size must be a whole number from 1 to 100"
}

{
  "status": "error",
  "message": "Invalid API key"
}

{
  "status": "error",
  "message": "Account is inactive"
}

GET

contact

get

Get Contacts

curl --request GET \
  --url https://api.callkaro.ai/contact/get \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.callkaro.ai/contact/get', 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.callkaro.ai/contact/get",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$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.callkaro.ai/contact/get"

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

	req.Header.Add("X-API-KEY", "<api-key>")

	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.callkaro.ai/contact/get")

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

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

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

{
  "status": "done",
  "contacts": [
    {
      "to_number": "919876543210",
      "channels": [],
      "attributes": {
        "first_name": "Rahul",
        "city": "Pune"
      },
      "created_at": "2026-10-27 11:42:05.118",
      "updated_at": "2026-10-27 11:42:05.118",
      "last_message_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1
  }
}

{
  "status": "error",
  "message": "page_size must be a whole number from 1 to 100"
}

{
  "status": "error",
  "message": "Invalid API key"
}

{
  "status": "error",
  "message": "Account is inactive"
}

Reads the contacts in your CRM, one page at a time, or looks up a single number with its current attributes.

Quick Example

curl "https://api.callkaro.ai/contact/get?page=1&page_size=20" \
  -H "X-API-KEY: YOUR_API_KEY"

Look up one number:

curl "https://api.callkaro.ai/contact/get?to_number=919876543210" \
  -H "X-API-KEY: YOUR_API_KEY"

Write the number without + in the URL. In a query string, + is read as a space.

Use Cases

Syncing out: copy your CRM contacts, and the attributes your agents collected, into your own database
Checking a lead: see whether a number is already a contact, and what is saved on it, before you create or update it

Pagination

Parameter	Default	Notes
`page`	`1`	Starts at 1
`page_size`	`20`	1 to 100
`to_number`	none	Returns only that contact, or an empty list

Contacts come back in the order the CRM shows them: the most recent conversation first, then contacts that have never messaged, most recently updated first. The response says how many pages there are:

"pagination": { "page": 1, "page_size": 20, "total": 57, "total_pages": 3 }

Keep asking for the next page until it reaches total_pages. A page past the end returns an empty contacts list.

New messages and edits move contacts up the list, so the pages can shift while you read them. When copying every contact, expect the odd contact to appear on two pages, and match on to_number.

What each contact contains

Field	Meaning
`to_number`	Phone number as stored: digits with country code, such as `919876543210`
`channels`	Channels the contact has been reached on, such as `whatsapp`
`attributes`	Each saved attribute and its value
`created_at`, `updated_at`	When the contact was added and last changed, in IST
`last_message_at`	When the last WhatsApp message was exchanged, in IST, or `null`

Errors worth handling

400 page or page_size out of range

page must be 1 or more, and page_size from 1 to 100, both whole numbers.

401 Invalid API key

The X-API-KEY header is missing or does not belong to any account.

403 Account is inactive

The account the key belongs to has been deactivated. Contact support.

Authorizations

X-API-KEY

string

header

required

API key from https://callkaro.ai/dashboard/api-key

Query Parameters

page

integer

default:1

Page number, starting at 1

Required range: x >= 1

page_size

integer

default:20

Contacts per page, at most 100

Required range: 1 <= x <= 100

to_number

string

Return only this number. Send it without +, which a URL reads as a space.

Response

One page of contacts

status

string

Example:

"done"

contacts

object[]

Show child attributes

pagination

object

Show child attributes

​Quick Example

​Use Cases

​Pagination

​What each contact contains

​Errors worth handling

Authorizations

Query Parameters

Response

Quick Example

Use Cases

Pagination

What each contact contains

Errors worth handling