Skip to content
Console
On this page

Adopt a sms number

Adopts an existing active carrier SMS number binding into one environment without purchasing a new number.

Adopts an existing active carrier SMS number binding into one environment without purchasing a new number.

  • Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/sms_numbers:adopt
  • Scope notify:write
  • Effect write — a successful call changes state.
  • Collection sms_numbers
  • Validate-only validate_only=true runs every check and writes nothing

Request

FieldTypeWhat it is
parentstringThe environment to bind the existing carrier number in. Required.
sms_number_idstringThe binding id; server-assigned when empty.
providerstringThe carrier provider ("telnyx"). Defaults to "telnyx" when empty.
provider_number_idstringCarrier phone number identifier to verify live before binding. Required.
phone_numberstringExpected E.164 phone number; must match the carrier record. Required.
messaging_profile_idstringExpected carrier messaging profile id; must match and be active. Required.
validate_onlyboolValidate against the carrier and local state without writing a binding.

Response

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/sms_numbers/{sms_number}.
uidstringsnum_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
specSmsNumberSpecDesired state. Required.
statusSmsNumberStatusObserved state. Output only.

ResourceMeta

FieldTypeWhat it is
generationint64Increases by one on every change to spec. Output only.
etagstringStrong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only.
create_timetimestampWhen the Resource was created. Output only.
update_timetimestampWhen the Resource last changed. Output only.
delete_timetimestampSet while the Resource is being deleted. Output only.
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.
creatorstringThe principal that created the Resource. Output only.

SmsNumberSpec

FieldTypeWhat it is
region_codestringISO two-letter country code. Required.
number_typestringlocal, mobile, toll_free, national or shared_cost. Required.
providerstringThe carrier; Telnyx is supported. Required.
upfront_cost_limitstringMaximum one-time USD price, as a decimal string. No quote over it is ordered. Required.
monthly_cost_limitstringMaximum recurring monthly USD price, as a decimal string. Required.

SmsNumberStatus

FieldTypeWhat it is
observed_generationint64The generation this status was computed from. Output only.
conditionsCondition[]Ready, Reconciling, Stalled. Output only.
receivingboolReceiving: an active binding whose number the carrier delivers to. Output only.
retired_timetimestampWhen the binding stopped receiving, if it has. Output only.
phone_numberstringThe provisioned E.164 number; empty until inventory selection. Output only.
carrier_accountstringThe platform carrier account reference, never a credential. Output only.
provider_number_idstringCarrier number identifier, when available. Output only.
order_idstringStable carrier order receipt; an uncertain purchase is reconciled, not repeated. Output only.
messaging_profile_idstringMessaging profile holding this number's webhook configuration. Output only.
state_reasonstringSafe reason for a pending or stalled provision; contains no message text. Output only.
upfront_coststringAccepted one-time price in USD. Output only.
monthly_coststringAccepted monthly price in USD. Output only.
voicemailVoicemailConfigDesired voicemail behavior. Configuring this does not attach the line. Output only.
voice_application_idstringReadback-verified standalone Call Control application. The line's owner attaches it separately; Notify never changes a DID's voice configuration. Output only.
voice_application_errorstringSafe provisioning error. Definite refusals are retryable after inventory readback; an unknown create outcome is never blindly repeated. Output only.

Condition

FieldTypeWhat it is
typestringThe condition type, for example Ready.
statusConditionStatusWhether the condition holds. One of true, false, unknown.
observed_generationint64The generation this observation was made against.
reasonstringA machine-readable UpperCamelCase reason.
messagestringA customer-safe human-readable message.
severitySeverityHow severe a FALSE condition is. One of info, warning, error.
transition_timetimestampWhen status last changed.

VoicemailConfig

FieldTypeWhat it is
greetingstringGreeting spoken before recording. Plain text, not SSML. Required.
retention_daysint32Delete both carrier and Storage audio, and the transcript, after 1–30 days. Required.
max_recording_durationdurationMaximum recording duration, 10–180 whole seconds (for example, "120s"). Required.

Errors

Every error arrives in the body Errors describes.

Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/sms_numbers:adopt" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messaging_profile_id":"…","phone_number":"…","provider_number_id":"…"}'