Resolve Contact
curl --request POST \
--url https://api.bland.ai/v1/contacts/resolve \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"phone_number": "<string>",
"email": "<string>",
"external_id": "<string>",
"name": "<string>",
"persona_id": "<string>",
"agent_number": "<string>",
"metadata": {}
}
'import requests
url = "https://api.bland.ai/v1/contacts/resolve"
payload = {
"phone_number": "<string>",
"email": "<string>",
"external_id": "<string>",
"name": "<string>",
"persona_id": "<string>",
"agent_number": "<string>",
"metadata": {}
}
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>',
name: '<string>',
persona_id: '<string>',
agent_number: '<string>',
metadata: {}
})
};
fetch('https://api.bland.ai/v1/contacts/resolve', 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/resolve",
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>',
'name' => '<string>',
'persona_id' => '<string>',
'agent_number' => '<string>',
'metadata' => [
]
]),
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/resolve"
payload := strings.NewReader("{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\",\n \"name\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"agent_number\": \"<string>\",\n \"metadata\": {}\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/resolve")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\",\n \"name\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"agent_number\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/contacts/resolve")
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 \"name\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"agent_number\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"contact": {
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"org_id": "11111111-2222-3333-4444-555555555555",
"name": "John Doe",
"metadata": {
"source": "api"
},
"created_at": "2025-07-22T10:30:00.000Z",
"updated_at": "2025-07-22T10:30:00.000Z"
},
"created": true
},
"errors": null
}
{
"data": {
"contact": {
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"org_id": "11111111-2222-3333-4444-555555555555",
"name": "John Doe",
"metadata": {
"source": "web_signup"
},
"created_at": "2025-07-20T10:30:00.000Z",
"updated_at": "2025-07-22T15:45:00.000Z"
},
"created": false
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "At least one identifier (phone_number, email, or external_id) is required"
}
]
}
Contacts
Resolve Contact
Find an existing contact or create a new one.
POST
/
v1
/
contacts
/
resolve
Resolve Contact
curl --request POST \
--url https://api.bland.ai/v1/contacts/resolve \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"phone_number": "<string>",
"email": "<string>",
"external_id": "<string>",
"name": "<string>",
"persona_id": "<string>",
"agent_number": "<string>",
"metadata": {}
}
'import requests
url = "https://api.bland.ai/v1/contacts/resolve"
payload = {
"phone_number": "<string>",
"email": "<string>",
"external_id": "<string>",
"name": "<string>",
"persona_id": "<string>",
"agent_number": "<string>",
"metadata": {}
}
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>',
name: '<string>',
persona_id: '<string>',
agent_number: '<string>',
metadata: {}
})
};
fetch('https://api.bland.ai/v1/contacts/resolve', 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/resolve",
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>',
'name' => '<string>',
'persona_id' => '<string>',
'agent_number' => '<string>',
'metadata' => [
]
]),
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/resolve"
payload := strings.NewReader("{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\",\n \"name\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"agent_number\": \"<string>\",\n \"metadata\": {}\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/resolve")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number\": \"<string>\",\n \"email\": \"<string>\",\n \"external_id\": \"<string>\",\n \"name\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"agent_number\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/contacts/resolve")
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 \"name\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"agent_number\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"contact": {
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"org_id": "11111111-2222-3333-4444-555555555555",
"name": "John Doe",
"metadata": {
"source": "api"
},
"created_at": "2025-07-22T10:30:00.000Z",
"updated_at": "2025-07-22T10:30:00.000Z"
},
"created": true
},
"errors": null
}
{
"data": {
"contact": {
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"org_id": "11111111-2222-3333-4444-555555555555",
"name": "John Doe",
"metadata": {
"source": "web_signup"
},
"created_at": "2025-07-20T10:30:00.000Z",
"updated_at": "2025-07-22T15:45:00.000Z"
},
"created": false
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "At least one identifier (phone_number, email, or external_id) is required"
}
]
}
Headers
string
required
Your API key for authentication.
Body Parameters
string
Phone number for the contact. At least one identifier is required.
string
Email address for the contact. At least one identifier is required.
string
External ID for the contact. At least one identifier is required.
string
Name of the contact.
string
Persona ID for memory scoping. Either
persona_id or agent_number should be provided for memory creation.string
Agent phone number for memory scoping. Either
persona_id or agent_number should be provided for memory creation.object
Custom metadata to associate with the contact.
Response
object
Response containing the contact and creation status.
object
The resolved contact object.
string
Unique identifier for the contact.
string
Organization ID the contact belongs to.
string
Contact’s name (if set).
object
Custom metadata associated with the contact.
string
ISO timestamp when the contact was created.
string
ISO timestamp when the contact was last updated.
boolean
Whether a new contact was created (true) or an existing one was found (false).
null
Error array (null on success).
{
"data": {
"contact": {
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"org_id": "11111111-2222-3333-4444-555555555555",
"name": "John Doe",
"metadata": {
"source": "api"
},
"created_at": "2025-07-22T10:30:00.000Z",
"updated_at": "2025-07-22T10:30:00.000Z"
},
"created": true
},
"errors": null
}
{
"data": {
"contact": {
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"org_id": "11111111-2222-3333-4444-555555555555",
"name": "John Doe",
"metadata": {
"source": "web_signup"
},
"created_at": "2025-07-20T10:30:00.000Z",
"updated_at": "2025-07-22T15:45:00.000Z"
},
"created": false
},
"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