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
Your API key for authentication.
Body Parameters
Phone number for the contact. At least one identifier is required.
Email address for the contact. At least one identifier is required.
External ID for the contact. At least one identifier is required.
Name of the contact.
Persona ID for memory scoping. Either
persona_id or agent_number should be provided for memory creation.Agent phone number for memory scoping. Either
persona_id or agent_number should be provided for memory creation.Custom metadata to associate with the contact.
Response
Response containing the contact and creation status.
The resolved contact object.
Unique identifier for the contact.
Organization ID the contact belongs to.
Contact’s name (if set).
Custom metadata associated with the contact.
ISO timestamp when the contact was created.
ISO timestamp when the contact was last updated.
Whether a new contact was created (true) or an existing one was found (false).
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