POSThttps://core-api.heysadie.ai/phone-numbers
phoneNumber name failoverNumber success data id country monthlySubscriptionCost createdAt updatedAt assistantName metadata timestamp version path error code message details fieldCreate phone number
Purchases a specific phone number for your tenant and registers it under your account. Use this endpoint after retrieving a list of available numbers from `GET /phone-numbers/available`. ### Required Fields - `phoneNumber`: The phone number you want to purchase (must exist in the available numbers list). - `name`: A friendly label for this phone number (e.g., "Main line", "Reservations"). Once successful, the number becomes part of your account and can be assigned to an assistant..
Try it in the API ExplorerExample request
curl -X POST "https://core-api.heysadie.ai/phone-numbers" \
-H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "value",
"name": "value",
"failoverNumber": "string"
}'Authentication
Authenticate with an API key in the Authorization header using the ApiKey scheme — see Authentication for how keys work and where to get them.
AuthorizationstringrequiredAPI key in the ApiKey scheme: ApiKey YOUR_API_KEY. Tenant keys authorize their own tenant; organization keys can act on any tenant in the organization.
X-Tenant-Idstring (uuid)optionalRequired when authenticating with an organization key — selects the tenant the request acts on. Omit with tenant keys.
Request
Body application/json · required
phoneNumberanyoptionalPhone number to purchase (must be from /phone-numbers/available)
nameanyoptionalLabel or name you want to associate with this number
failoverNumberstringoptionalFailover phone number in E.164 format (e.g., +1234567890) for call transfer on assistant failures
Responses
successbooleanrequireddataobjectoptionalShow 7 child properties
idstringrequiredphoneNumberstringrequiredcountrystringrequiredmonthlySubscriptionCoststring | nullrequiredcreatedAtstring (date-time) | string (date) | number | nullrequiredupdatedAtstring (date-time) | string (date) | number | nullrequiredassistantNamestring | nullrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional400
successbooleanrequirederrorobjectoptionalShow 3 child properties
codeenumrequired"VALIDATION_ERROR"messagestringrequireddetailsobject[]optionalShow 2 item properties
fieldstringrequiredmessagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional401
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"UNAUTHORIZED"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional403
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"FORBIDDEN"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional404
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"RESOURCE_NOT_FOUND"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional500
successbooleanrequirederrorobjectoptionalShow 2 child properties
codeenumrequired"INTERNAL_SERVER_ERROR"messagestringrequiredmetadataobjectoptionalShow 3 child properties
timestampstringrequiredversionstringrequiredpathstringoptional