Phone & voice · Branded Calling
Dry-runs a caller identity before creating it without changing anything.
https://api.pozy.ai/v1/branded-calling/identities/preflightGuide: Branded calling
Request
Send your API key as Authorization: Bearer pz_live_.... Read-only keys cannot call it. Keys with the telephony resource group disabled get 403 resource_group_disabled. Authentication
Request body
application/json, required
enterpriseIdstringrequireddisplayNamestringrequired1 to 35 characters.
callReasonsarray of stringrequiredAt least 1 item. Up to 10 items. Each item: up to 64 characters.
logoUrlstringauthorizerobjectrequirednamestringrequiredUp to 255 characters.
emailstring (email)required
referencesobjectrequiredbusinessarray of objectrequiredAt least 2 items. Up to 2 items.
7 child fields
fullNamestringrequiredUp to 255 characters.
jobTitlestringUp to 255 characters.
organizationstringUp to 255 characters.
relationshipToRegistrantstringUp to 255 characters.
phoneNumberstringrequiredemailstring (email)requiredtimezonestringrequired
financialobjectrequired7 child fields
fullNamestringrequiredUp to 255 characters.
jobTitlestringUp to 255 characters.
organizationstringUp to 255 characters.
relationshipToRegistrantstringUp to 255 characters.
phoneNumberstringrequiredemailstring (email)requiredtimezonestringrequired
Example
curl -X POST "https://api.pozy.ai/v1/branded-calling/identities/preflight" \
-H "Authorization: Bearer $POZY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enterpriseId": "66496a86752378ad82057ff6",
"displayName": "Acme",
"callReasons": [
"string"
],
"authorizer": {
"name": "Acme",
"email": "alex@example.com"
},
"references": {
"business": [
{
"fullName": "Acme",
"phoneNumber": "+14155550123",
"email": "alex@example.com",
"timezone": "America/New_York"
}
],
"financial": {
"fullName": "Acme",
"phoneNumber": "+14155550123",
"email": "alex@example.com",
"timezone": "America/New_York"
}
}
}'const res = await fetch("https://api.pozy.ai/v1/branded-calling/identities/preflight", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.POZY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
enterpriseId: "66496a86752378ad82057ff6",
displayName: "Acme",
callReasons: [
"string"
],
authorizer: {
name: "Acme",
email: "alex@example.com"
},
references: {
business: [
{
fullName: "Acme",
phoneNumber: "+14155550123",
email: "alex@example.com",
timezone: "America/New_York"
}
],
financial: {
fullName: "Acme",
phoneNumber: "+14155550123",
email: "alex@example.com",
timezone: "America/New_York"
}
}
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);import os
import requests
resp = requests.post(
"https://api.pozy.ai/v1/branded-calling/identities/preflight",
headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
json={
"enterpriseId": "66496a86752378ad82057ff6",
"displayName": "Acme",
"callReasons": [
"string",
],
"authorizer": {
"name": "Acme",
"email": "alex@example.com",
},
"references": {
"business": [
{
"fullName": "Acme",
"phoneNumber": "+14155550123",
"email": "alex@example.com",
"timezone": "America/New_York",
},
],
"financial": {
"fullName": "Acme",
"phoneNumber": "+14155550123",
"email": "alex@example.com",
"timezone": "America/New_York",
},
},
},
timeout=30,
)
resp.raise_for_status()
print(resp.json())Response
200 on success
okbooleanfindingsarray of objectcodestringOne of
display-name-mismatch,call-reasons-manual,authorizer-free-mail,authorizer-domain-mismatch,reference-phone-duplicate,reference-internal,reference-financial-free-mail,reference-timezone-invalid,logo-unreachable.severitystringOne of
block,warn.fieldstringmessagestring
{
"ok": true,
"findings": [
{
"code": "display-name-mismatch",
"severity": "block",
"field": "string",
"message": "Hello from Pozy"
}
]
}Errors
Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:
| 400 | invalid_request_error | A parameter or body field is missing or invalid. param names it. |
| 401 | authentication_error | The API key is missing, revoked or expired. |
| 403 | permission_error | The key is read-only, scoped to other profiles, or has this resource group disabled. |
| 429 | rate_limit_error | Too many requests this minute. Wait for Retry-After seconds. |
Every code is listed in Errors.