phones

Numbers and outbound SMS for a persona — client.phones.

Numbers hang off an identity. Five methods. API detail: Email & SMS.

​

provision

client.phones.provision(identityId: string, body: PhoneProvision): Promise<PhoneNumber>

POST /v1/identities/{id}/phones. Answers 202, not 201: the number exists and can receive immediately, but outbound waits on a carrier registration decision.

tier · "sole_prop" | "standard" · required

The carrier registration tier.

legal_name · string · required

The registered legal name.

country · string

ISO country; defaults server-side.

tax_id · string

standard only. Write-through: handed to the carrier and never stored.

contact_phone · string

sole_prop only — the handset that receives the verification passcode. Never stored.

e164 · string

Request a specific number.

owning_agent_id · string

The agent inbound texts wake. Checked before the purchase; null if the agent was deleted mid-purchase.

​

list

client.phones.list(identityId: string, query?: { limit?: number }): Promise<Page<PhoneNumber>>

GET /v1/identities/{id}/phones — including each number’s campaign/compliance status.

​

update

client.phones.update(identityId: string, phoneId: string, body: { owning_agent_id: string | null }): Promise<PhoneNumber>

PATCH /v1/identities/{id}/phones/{phone_id}. Sets the agent inbound texts wake, or clears it with null. Each text that passes the guards then starts a session for that agent, as this persona, billed to your credits; earlier texts are not woken.

• The agent must hold the persona, or the call fails validation_failed.
• A deleted agent fails not_found.
• The woken agent can’t reply by text: no agent tool sends SMS.

​

release

client.phones.release(identityId: string, phoneId: string): Promise<Deleted>

DELETE /v1/identities/{id}/phones/{phone_id}. Irreversible at the carrier — the number returns to the pool and cannot be reclaimed.

​

send

client.phones.send(identityId: string, phoneId: string, body: { to: string; text: string }): Promise<SmsSendReceipt>

POST /v1/identities/{id}/phones/{phone_id}/send. Answers a 202 receipt { accepted, from, to, sent_at }. Refused with compliance_pending until the carrier approves the campaign — that is a carrier rule, not ours.