List Contacts
curl --request GET \
--url https://api.bland.ai/v1/contacts \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v1/contacts"
headers = {"authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v1/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.bland.ai/v1/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: <authorization>"
],
]);
$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.bland.ai/v1/contacts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.bland.ai/v1/contacts")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/contacts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"org_id": "11111111-2222-3333-4444-555555555555",
"name": "Sarah Chen",
"metadata": {
"source": "inbound_call"
},
"created_at": "2025-07-20T10:30:00.000Z",
"updated_at": "2025-07-23T09:15:00.000Z",
"identifiers": [
{
"id": "ident-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb",
"contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"identifier_type": "phone_number",
"identifier_value": "+14155550192",
"is_primary": true
}
],
"memories": [
{
"id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"persona_id": "persona-12345678",
"agent_number": null,
"summary": "Customer called about order #8821 which was delayed. Follow-up SMS confirmed the order shipped and is now in transit. Expected delivery July 25.",
"facts": {
"name": "Sarah Chen",
"phone": "+14155550192",
"preferred_contact": "sms",
"timezone": "America/Los_Angeles"
},
"recent_messages": [
{
"role": "user",
"content": "Has my order shipped yet?",
"channel": "sms",
"timestamp": "2025-07-23T09:10:00.000Z"
},
{
"role": "assistant",
"content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.",
"channel": "sms",
"timestamp": "2025-07-23T09:10:05.000Z"
}
],
"open_items": [
{
"type": "follow_up",
"description": "Confirm delivery of order #8821 on July 25",
"created_at": "2025-07-23T09:10:00.000Z",
"priority": "medium",
"related_to": {
"entity_type": "order",
"entity_id": "order-8821"
}
}
],
"entities": [
{
"entity_type": "order",
"entity_id": "order-8821",
"facts": {
"order_number": "#8821",
"status": "in_transit",
"carrier": "UPS",
"expected_delivery": "2025-07-25"
},
"status": "in_transit",
"last_discussed_at": "2025-07-23T09:10:00.000Z",
"notes": null
}
]
}
]
}
],
"pagination": {
"total": 100,
"limit": 50,
"offset": 0,
"has_more": true
},
"errors": null
}
Contacts
List Contacts
List all contacts for your organization. Each contact includes identifiers, contact_memories (per persona/agent), and memory entities. Paginated.
GET
/
v1
/
contacts
List Contacts
curl --request GET \
--url https://api.bland.ai/v1/contacts \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v1/contacts"
headers = {"authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v1/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.bland.ai/v1/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: <authorization>"
],
]);
$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.bland.ai/v1/contacts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.bland.ai/v1/contacts")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/contacts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"org_id": "11111111-2222-3333-4444-555555555555",
"name": "Sarah Chen",
"metadata": {
"source": "inbound_call"
},
"created_at": "2025-07-20T10:30:00.000Z",
"updated_at": "2025-07-23T09:15:00.000Z",
"identifiers": [
{
"id": "ident-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb",
"contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"identifier_type": "phone_number",
"identifier_value": "+14155550192",
"is_primary": true
}
],
"memories": [
{
"id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"persona_id": "persona-12345678",
"agent_number": null,
"summary": "Customer called about order #8821 which was delayed. Follow-up SMS confirmed the order shipped and is now in transit. Expected delivery July 25.",
"facts": {
"name": "Sarah Chen",
"phone": "+14155550192",
"preferred_contact": "sms",
"timezone": "America/Los_Angeles"
},
"recent_messages": [
{
"role": "user",
"content": "Has my order shipped yet?",
"channel": "sms",
"timestamp": "2025-07-23T09:10:00.000Z"
},
{
"role": "assistant",
"content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.",
"channel": "sms",
"timestamp": "2025-07-23T09:10:05.000Z"
}
],
"open_items": [
{
"type": "follow_up",
"description": "Confirm delivery of order #8821 on July 25",
"created_at": "2025-07-23T09:10:00.000Z",
"priority": "medium",
"related_to": {
"entity_type": "order",
"entity_id": "order-8821"
}
}
],
"entities": [
{
"entity_type": "order",
"entity_id": "order-8821",
"facts": {
"order_number": "#8821",
"status": "in_transit",
"carrier": "UPS",
"expected_delivery": "2025-07-25"
},
"status": "in_transit",
"last_discussed_at": "2025-07-23T09:10:00.000Z",
"notes": null
}
]
}
]
}
],
"pagination": {
"total": 100,
"limit": 50,
"offset": 0,
"has_more": true
},
"errors": null
}
Headers
string
required
Your API key for authentication.
Query Parameters
integer
Maximum number of contacts to return. Default 50, max 200.
integer
Number of contacts to skip (for pagination). Default 0.
Response
array
Array of contact objects. Each includes identifiers, memories (with entities).
object
Pagination metadata (total, limit, offset, has_more).
integer
Total number of contacts in the org.
integer
Limit used for this request.
integer
Offset used for this request.
boolean
Whether more contacts exist after this page.
null
Error array (null on success).
{
"data": [
{
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"org_id": "11111111-2222-3333-4444-555555555555",
"name": "Sarah Chen",
"metadata": {
"source": "inbound_call"
},
"created_at": "2025-07-20T10:30:00.000Z",
"updated_at": "2025-07-23T09:15:00.000Z",
"identifiers": [
{
"id": "ident-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb",
"contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"identifier_type": "phone_number",
"identifier_value": "+14155550192",
"is_primary": true
}
],
"memories": [
{
"id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"persona_id": "persona-12345678",
"agent_number": null,
"summary": "Customer called about order #8821 which was delayed. Follow-up SMS confirmed the order shipped and is now in transit. Expected delivery July 25.",
"facts": {
"name": "Sarah Chen",
"phone": "+14155550192",
"preferred_contact": "sms",
"timezone": "America/Los_Angeles"
},
"recent_messages": [
{
"role": "user",
"content": "Has my order shipped yet?",
"channel": "sms",
"timestamp": "2025-07-23T09:10:00.000Z"
},
{
"role": "assistant",
"content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.",
"channel": "sms",
"timestamp": "2025-07-23T09:10:05.000Z"
}
],
"open_items": [
{
"type": "follow_up",
"description": "Confirm delivery of order #8821 on July 25",
"created_at": "2025-07-23T09:10:00.000Z",
"priority": "medium",
"related_to": {
"entity_type": "order",
"entity_id": "order-8821"
}
}
],
"entities": [
{
"entity_type": "order",
"entity_id": "order-8821",
"facts": {
"order_number": "#8821",
"status": "in_transit",
"carrier": "UPS",
"expected_delivery": "2025-07-25"
},
"status": "in_transit",
"last_discussed_at": "2025-07-23T09:10:00.000Z",
"notes": null
}
]
}
]
}
],
"pagination": {
"total": 100,
"limit": 50,
"offset": 0,
"has_more": true
},
"errors": null
}
Docs for agents: llms.txt
Was this page helpful?
⌘I