Find Contact
curl --request POST \
--url https://api.bland.ai/v1/contacts/find \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"phone_number": "<string>",
"email": "<string>",
"external_id": "<string>"
}
'import requests
url = "https://api.bland.ai/v1/contacts/find"
payload = {
"phone_number": "<string>",
"email": "<string>",
"external_id": "<string>"
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({phone_number: '<string>', email: '<string>', external_id: '<string>'})
};
fetch('https://api.bland.ai/v1/contacts/find', 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/find",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone_number' => '<string>',
'email' => '<string>',
'external_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v1/contacts/find"
payload := strings.NewReader("{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v1/contacts/find")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/contacts/find")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\"\n}"
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
}
]
}
]
},
"errors": null
}
{
"data": null,
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "At least one identifier (phone_number, email, or external_id) is required"
}
]
}
Contacts
Find Contact
Find a contact by phone number, email, or external ID. Returns the contact with all identifiers, contact_memories (per persona/agent), and memory entities.
POST
/
v1
/
contacts
/
find
Find Contact
curl --request POST \
--url https://api.bland.ai/v1/contacts/find \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"phone_number": "<string>",
"email": "<string>",
"external_id": "<string>"
}
'import requests
url = "https://api.bland.ai/v1/contacts/find"
payload = {
"phone_number": "<string>",
"email": "<string>",
"external_id": "<string>"
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({phone_number: '<string>', email: '<string>', external_id: '<string>'})
};
fetch('https://api.bland.ai/v1/contacts/find', 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/find",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone_number' => '<string>',
'email' => '<string>',
'external_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v1/contacts/find"
payload := strings.NewReader("{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v1/contacts/find")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/contacts/find")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\"\n}"
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
}
]
}
]
},
"errors": null
}
{
"data": null,
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "At least one identifier (phone_number, email, or external_id) is required"
}
]
}
Headers
Your API key for authentication.
Body Parameters
Phone number to search for. At least one identifier is required.
Email address to search for. At least one identifier is required.
External ID to search for. At least one identifier is required.
Response
Returns the contact with related data, ornull if not found.
The contact object with identifiers, memories, and entities. Null if no contact found.
Unique identifier for the contact.
Organization ID the contact belongs to.
Contact’s name (if set).
Custom metadata associated with the contact.
Contact identifiers (phone_number, email, external_id) for this contact.
Contact memory objects, one per persona or agent. Each includes summary, facts, recent_messages, open_items, and entities (memory_entity records).
Entity-scoped facts (e.g. bookings, orders) for that memory.
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
}
]
}
]
},
"errors": null
}
{
"data": null,
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "At least one identifier (phone_number, email, or external_id) is required"
}
]
}
Docs for agents: llms.txt
Was this page helpful?
⌘I