curl --request POST \
--url https://api.reflecto.dev/v1/sms-agent/contact-queries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "Richa mobile"
}
'import requests
url = "https://api.reflecto.dev/v1/sms-agent/contact-queries"
payload = { "query": "Richa mobile" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: 'Richa mobile'})
};
fetch('https://api.reflecto.dev/v1/sms-agent/contact-queries', 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.reflecto.dev/v1/sms-agent/contact-queries",
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([
'query' => 'Richa mobile'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.reflecto.dev/v1/sms-agent/contact-queries"
payload := strings.NewReader("{\n \"query\": \"Richa mobile\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.reflecto.dev/v1/sms-agent/contact-queries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"Richa mobile\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reflecto.dev/v1/sms-agent/contact-queries")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"Richa mobile\"\n}"
response = http.request(request)
puts response.read_body{
"status": "ok",
"candidates": [
{
"handle": "ch_q3V9xK2mP0aL7bN4cR1sTw",
"name": "Richa Sharma",
"label": "Mobile"
},
{
"handle": "ch_Zx8wV7uT6sR5qP4oN3mL2k",
"name": "Richa Sharma",
"label": "Work"
}
]
}Look up a saved contact to text, by name
The find_contact MCP tool’s backing endpoint. Asks the user’s phone to search its contacts by name and waits up to 15 seconds for the answer. Returns up to 5 candidates, each a display name, a number-type label and an opaque single-use handle (10-minute lifetime) for POST /v1/sms-agent/sends.
No phone number is ever returned, whole or in part, and a query that is mostly digits is refused (400 invalid_query) so this cannot become a reverse lookup.
Not end-to-end encrypted. This is Reflecto’s server-as-sender path: the request passes through Reflecto’s server in memory, is encrypted to the phone with the server’s key, and is never stored.
Requires an OAuth token from a connected assistant holding sms:send, and a paired phone running a Reflecto build that supports assistant texting (426 / 428 otherwise). The user must also have switched on “Let assistants send texts” on the phone, or the answer is disabled.
curl --request POST \
--url https://api.reflecto.dev/v1/sms-agent/contact-queries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "Richa mobile"
}
'import requests
url = "https://api.reflecto.dev/v1/sms-agent/contact-queries"
payload = { "query": "Richa mobile" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: 'Richa mobile'})
};
fetch('https://api.reflecto.dev/v1/sms-agent/contact-queries', 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.reflecto.dev/v1/sms-agent/contact-queries",
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([
'query' => 'Richa mobile'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.reflecto.dev/v1/sms-agent/contact-queries"
payload := strings.NewReader("{\n \"query\": \"Richa mobile\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.reflecto.dev/v1/sms-agent/contact-queries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"Richa mobile\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reflecto.dev/v1/sms-agent/contact-queries")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"Richa mobile\"\n}"
response = http.request(request)
puts response.read_body{
"status": "ok",
"candidates": [
{
"handle": "ch_q3V9xK2mP0aL7bN4cR1sTw",
"name": "Richa Sharma",
"label": "Mobile"
},
{
"handle": "ch_Zx8wV7uT6sR5qP4oN3mL2k",
"name": "Richa Sharma",
"label": "Work"
}
]
}Authorizations
Body
Response
The phone's answer, or phone_unreachable if it did not answer within 15 s. Every outcome is a 200 — only ok carries candidates.
ok carries 1–5 candidates. no_match / too_many (more than 5 — ask for a more specific name) carry none. disabled = the user has not switched on “Let assistants send texts” on the phone. phone_unreachable = the phone did not answer within 15 s. The remaining values are phone-side refusals: too_many_lookups (30/hour), no_contacts_permission, no_sms_permission, invalid_query, contacts_unavailable.
ok, no_match, too_many, disabled, too_many_lookups, no_contacts_permission, no_sms_permission, invalid_query, contacts_unavailable, phone_unreachable "ok"