Messaging · iMessage
Orders a new iMessage sender.
POST
https://api.pozy.ai/v1/imessage/senders/orderNot available yetorderImessageSender
Guide: iMessage
Request
Send your API key as Authorization: Bearer pz_live_.... Read-only keys cannot call it. Authentication
This endpoint is not available yet. Calls return 403 feature_not_available.
Request body
application/json, required
profileIdstringrequiredkindstringrequiredOne of
phone,email.regionstringOne of
US,GB.availableNumberIdstringzipCodestringMatches
^[0-9]{5}$.emailNamestringemailDomainstringdisplayNamestringUp to 100 characters.
purchaseIntentIdstringUp to 100 characters.
contactobjectfirstNamestringrequiredUp to 64 characters.
lastNamestringUp to 64 characters.
photoUrlstring (URL)
Example
curl -X POST "https://api.pozy.ai/v1/imessage/senders/order" \
-H "Authorization: Bearer $POZY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"profileId": "6a0b6573846efc28aaa9a3ff",
"kind": "phone"
}'const res = await fetch("https://api.pozy.ai/v1/imessage/senders/order", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.POZY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
profileId: "6a0b6573846efc28aaa9a3ff",
kind: "phone"
}),
});
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/imessage/senders/order",
headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
json={
"profileId": "6a0b6573846efc28aaa9a3ff",
"kind": "phone",
},
timeout=30,
)
resp.raise_for_status()
print(resp.json())Response
202 on success
successbooleansenderobject13 child fields
idstringkindstringOne of
phone,email.regionstringOne of
US,GB. Can be null.handlestringCan be null.
optInLinkstringCan be null.
statusstringOne of
ordering,awaiting_payment,activating,active,suspended,canceled,failed.priceCentsintegerproviderstringprofileIdstringdisplayNamestringCan be null.
failureReasonstringCan be null.
accountIdstringCan be null.
createdAtstring (date-time)
202 response
{
"success": true,
"sender": {
"id": "6bfebd43ddc270f6d2c56fc5",
"kind": "phone",
"region": "US",
"handle": "acme",
"optInLink": "string",
"status": "ordering",
"priceCents": 1,
"provider": "string",
"profileId": "6a0b6573846efc28aaa9a3ff",
"displayName": "Acme",
"failureReason": "string",
"accountId": "696e0b682d0a31188e7a2ba9",
"createdAt": "2026-10-02T09:00:00.000Z"
}
}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.
More in iMessage
GETList iMessage sendersPOSTRegister an iMessage senderGETList iMessage sender ordersGETGet iMessage sender statusPATCHUpdate an iMessage senderDELCancel an iMessage senderGETList iMessage audienceGETList iMessage sandbox contactsPOSTAdd an iMessage sandbox contactDELRemove an iMessage sandbox contactPOSTSubscribe or opt out an iMessage contactPOSTCreate a tracked iMessage opt-in linkGETList instantly available iMessage numbersPOSTReserve an available iMessage numberPOSTStart an iMessage group chatGETGet an iMessage groupPATCHRename an iMessage group or change its photoPOSTAdd a participant to an iMessage groupDELRemove a participant from an iMessage group