@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/phoneNumbers.md

@@ -0,0 +1,777 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.phoneNumbers`: Phone Numbers
+
+16 operations (3 read, 8 write, 3 destructive, 1 billable, 1 external).
+
+No hand-written client covers this area. Call it through `g8.api.phoneNumbers.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [phoneNumbers.d.ts](phoneNumbers.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`deleteVoiceNumber`](#op-deletevoicenumber) | `DELETE /api/v1/voice/numbers` | destructive | `voice:delete` | Deregister a number from the voice platform |
+| [`getPhoneA2pStatus`](#op-getphonea2pstatus) | `GET /api/v1/phone-numbers/a2p/status` | read | `voice:read` | Get Phone A2P Status |
+| [`getVoiceAnsweringAgent`](#op-getvoiceansweringagent) | `GET /api/v1/voice/numbers/answering-agent` | read | `voice:read` | Which agent answers a number |
+| [`provisionVoiceNumber`](#op-provisionvoicenumber) | `POST /api/v1/voice/numbers/provision` | write | `voice:write` | Register a number with the voice platform |
+| [`purchasePhoneNumber`](#op-purchasephonenumber) | `POST /api/v1/phone-numbers/purchase` | billable | `voice:run` | Buy a phone number |
+| [`reconcileA2pRegistration`](#op-reconcilea2pregistration) | `POST /api/v1/phone-numbers/a2p/reconcile` | write | `voice:write` | Re-run A2P registration for stuck numbers |
+| [`releasePhoneNumber`](#op-releasephonenumber) | `POST /api/v1/phone-numbers/release` | destructive | `voice:delete` | Release a phone number |
+| [`resetVoiceDailyCounts`](#op-resetvoicedailycounts) | `DELETE /api/v1/voice/numbers/daily-counts` | destructive | `voice:delete` | Reset today's per-number dialing counters |
+| [`saveA2pInputs`](#op-savea2pinputs) | `POST /api/v1/phone-numbers/a2p/inputs` | write | `voice:write` | Save A2P brand and campaign details |
+| [`searchAvailablePhoneNumbers`](#op-searchavailablephonenumbers) | `POST /api/v1/phone-numbers/search` | read | `voice:read` | Search Available Phone Numbers |
+| [`startA2pRegistration`](#op-starta2pregistration) | `POST /api/v1/phone-numbers/a2p/register` | external | `voice:run` | Submit A2P 10DLC registration |
+| [`updatePhoneAssignee`](#op-updatephoneassignee) | `PATCH /api/v1/phone-numbers/update-assignee` | write | `voice:write` | Reassign a phone number |
+| [`updatePhoneCapabilities`](#op-updatephonecapabilities) | `PATCH /api/v1/phone-numbers/update-capabilities` | write | `voice:write` | Switch a number between dialer and voice AI |
+| [`updateVoiceAssignee`](#op-updatevoiceassignee) | `PATCH /api/v1/voice/numbers/assignee` | write | `voice:write` | Set a number's voice-side assignee |
+| [`updateVoiceInboundType`](#op-updatevoiceinboundtype) | `PATCH /api/v1/voice/numbers/inbound-type` | write | `voice:write` | Change what answers a number's inbound calls |
+| [`verifyVoiceCallerId`](#op-verifyvoicecallerid) | `POST /api/v1/voice/numbers/verify-caller-id/{phone_number}` | write | `voice:write` | Verify a Telnyx number as a caller ID |
+
+---
+
+<a id="op-deletevoicenumber"></a>
+
+### `g8.api.phoneNumbers.deleteVoiceNumber(input)`
+
+**Deregister a number from the voice platform**
+
+- HTTP: `DELETE /api/v1/voice/numbers`
+- operationId: `delete_voice_number_voice_numbers_delete` (also callable as `g8.api.call("delete_voice_number_voice_numbers_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `voice:delete`
+
+Tear down a number's SIP trunks, dispatch rules and carrier routing.
+
+DOES NOT RELEASE THE NUMBER. The organisation still owns it and is still
+billed for it by the carrier - it simply stops being answerable. To give it
+back, use `POST /phone-numbers/release`, which does this and the carrier
+release and the local record.
+
+Voice's own handler identifies the number by value with no tenant check, so
+this route first asserts the caller's organisation owns it. A number that
+exists in voice but was never recorded against this organisation is a 404.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `VoiceNumberDeleteRequest` | yes | Request body; fields below. |
+
+Body fields (`VoiceNumberDeleteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.number` | `string` | yes | The number to deregister, E.164. |
+| `body.provider` | `"twilio" \| "telnyx"` | no | The carrier to deregister from. Must match how the number was registered, or the provider-side cleanup silently does nothing while the local record still disappears. default `"twilio"` |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.phoneNumbers.deleteVoiceNumber({ body: { number: "example" } });
+```
+
+---
+
+<a id="op-getphonea2pstatus"></a>
+
+### `g8.api.phoneNumbers.getPhoneA2pStatus(input?)`
+
+**Get Phone A2P Status**
+
+- HTTP: `GET /api/v1/phone-numbers/a2p/status`
+- operationId: `get_phone_a2p_status_phone_numbers_a2p_status_get` (also callable as `g8.api.call("get_phone_a2p_status_phone_numbers_a2p_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `voice:read`
+
+Where the org's A2P 10DLC registration stands, and whether its inputs are complete.
+
+**Input**: none.
+
+**Returns** `ApiResponse_PhoneA2pStatusPayload_`: the envelope `{ data: PhoneA2pStatusPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.getPhoneA2pStatus();
+```
+
+---
+
+<a id="op-getvoiceansweringagent"></a>
+
+### `g8.api.phoneNumbers.getVoiceAnsweringAgent(input?)`
+
+**Which agent answers a number**
+
+- HTTP: `GET /api/v1/voice/numbers/answering-agent`
+- operationId: `get_voice_answering_agent_voice_numbers_answering_agent_get` (also callable as `g8.api.call("get_voice_answering_agent_voice_numbers_answering_agent_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `voice:read`
+
+Who picks up when this number is called.
+
+A number lives on the company profile as free text while the agent that
+answers it is bound on that agent's identity, so the link is not readable
+from either side alone. This resolves it.
+
+READ-ONLY by design, and the design is load-bearing: resolving a route for
+real marks directory members as engaged, so this deliberately does not.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.number` | `string` | no | The number to resolve, E.164. OPTIONAL: with no main line set yet, omitting it returns the organisation's receptionists, which is exactly the list to choose one from. default `""` |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.getVoiceAnsweringAgent();
+```
+
+---
+
+<a id="op-provisionvoicenumber"></a>
+
+### `g8.api.phoneNumbers.provisionVoiceNumber(input)`
+
+**Register a number with the voice platform**
+
+- HTTP: `POST /api/v1/voice/numbers/provision`
+- operationId: `provision_voice_number_voice_numbers_provision_post` (also callable as `g8.api.call("provision_voice_number_voice_numbers_provision_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `voice:write`
+
+Wire an already-owned number into the voice platform.
+
+BUYS NOTHING. Voice calls this operation `purchase` and it is published
+here as `provision` deliberately: it creates SIP trunks and dispatch rules
+for a number you already hold, while `POST /phone-numbers/purchase` is the
+one that spends credits and buys a DID. Two operations both called
+"purchase", one of which takes money and one of which does not, is not a
+distinction to leave to a docstring.
+
+IDEMPOTENT: a number already registered comes back as success rather than
+an error, and an unverified Telnyx number has its caller-ID verification
+re-queued on the way through.
+
+Reach for this to repair a purchase whose voice half failed, or to adopt a
+number bought outside graph8. `org_id` is taken from the API key.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `VoiceNumberProvisionRequest` | yes | Request body; fields below. |
+
+Body fields (`VoiceNumberProvisionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.number` | `string` | yes | The number to register, E.164. You must already own it. |
+| `body.assigned_to` | `string \| null` | no | Email of the person this number rings for. REQUIRED in practice for a `work` number: without it no phone-directory row is created, so the receptionist can never route to them by name. |
+| `body.dialer` | `boolean` | no | Provision as a dialer number (no LiveKit). default `false` |
+| `body.inbound_type` | `"ai" \| "sdr" \| "dialer" \| "work" \| null` | no | How inbound calls are answered. Ignored when `dialer` or `work` is set - those paths provision no LiveKit trunks at all and the type is forced to `dialer` / `work` respectively. default `"ai"` |
+| `body.provider` | `"twilio" \| "telnyx"` | no | Which carrier holds the number. default `"twilio"` |
+| `body.work` | `boolean` | no | Provision as someone's personal work phone. Implies `dialer`. default `false` |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.provisionVoiceNumber({ body: { number: "example" } });
+```
+
+---
+
+<a id="op-purchasephonenumber"></a>
+
+### `g8.api.phoneNumbers.purchasePhoneNumber(input)`
+
+**Buy a phone number**
+
+- HTTP: `POST /api/v1/phone-numbers/purchase`
+- operationId: `purchase_phone_number_phone_numbers_purchase_post` (also callable as `g8.api.call("purchase_phone_number_phone_numbers_purchase_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `voice:run`
+
+Buy a number from Twilio or Telnyx. THIS SPENDS CREDITS AND REAL MONEY.
+
+Charged on PURCHASE, not on first use: the handler holds credits, buys the
+number from the carrier, stores it, registers it with the voice platform
+and only then converts the hold to a charge. A number bought and never
+dialled has still cost.
+
+Not idempotent by number - buy the same number twice and the second call
+is a 409 rather than a second charge, but a retry after a timeout you
+cannot see the outcome of may have already succeeded. Send an
+`Idempotency-Key` header; every POST on this API honours it.
+
+`402` means insufficient credits and is the one failure worth handling
+distinctly - the number was not bought and nothing was charged.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PurchasePhoneRequest` | yes | Request body; fields below. |
+
+Body fields (`PurchasePhoneRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.phone_number` | `string` | yes | The number to buy, E.164 (e.g. `+14155550123`). Search for one first. |
+| `body.provider` | `"twilio" \| "telnyx"` | yes | Which carrier to buy it from. |
+| `body.assignee` | `string \| null` | no | Who the number belongs to. Defaults to the identity behind the API key, matching the app - it is never taken from the body's organisation, because there is no organisation in the body. |
+| `body.dialer` | `boolean` | no | True provisions a dialer number; false provisions a voice-AI number. default `true` |
+| `body.work` | `boolean` | no | True makes this someone's personal work phone - provisioned like a dialer number but tagged `work`, and never part of the outbound caller-ID rotation pool. default `false` |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.phoneNumbers.purchasePhoneNumber({ body: { phone_number: "+15555550100", provider: "twilio" } });
+```
+
+---
+
+<a id="op-reconcilea2pregistration"></a>
+
+### `g8.api.phoneNumbers.reconcileA2pRegistration(input?)`
+
+**Re-run A2P registration for stuck numbers**
+
+- HTTP: `POST /api/v1/phone-numbers/a2p/reconcile`
+- operationId: `reconcile_a2p_registration_phone_numbers_a2p_reconcile_post` (also callable as `g8.api.call("reconcile_a2p_registration_phone_numbers_a2p_reconcile_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `voice:write`
+
+Re-attach this organisation's pending or failed numbers to its A2P
+messaging service.
+
+The repair step, not the registration step. A worker already does this
+every six hours; this is how to stop waiting for it after fixing whatever
+made a number fail. It re-runs against numbers whose status is pending or
+failed and leaves registered ones alone, so it is safe to call repeatedly.
+
+Tiered as an ordinary write rather than a spend: it reconciles state the
+`/a2p/register` submission already paid for and starts no new registration.
+
+`503` means the messaging service is not configured for this environment,
+which is a deployment fact rather than anything the caller did wrong.
+
+**Input**: none.
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.reconcileA2pRegistration();
+```
+
+---
+
+<a id="op-releasephonenumber"></a>
+
+### `g8.api.phoneNumbers.releasePhoneNumber(input)`
+
+**Release a phone number**
+
+- HTTP: `POST /api/v1/phone-numbers/release`
+- operationId: `release_phone_number_phone_numbers_release_post` (also callable as `g8.api.call("release_phone_number_phone_numbers_release_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `voice:delete`
+
+Give a number back to the carrier. IRREVERSIBLE.
+
+The number returns to the provider's pool and can be bought by anyone,
+including a competitor. Inbound calls and messages to it stop reaching
+this organisation immediately; there is no grace period and no undo.
+
+Order matters and is not transactional: the carrier release happens first,
+then voice deregistration (best-effort), then the local record. A failure
+after the carrier release leaves the number gone but the record behind -
+which is why this returns the outcome rather than a bare 204.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ReleasePhoneRequest` | yes | Request body; fields below. |
+
+Body fields (`ReleasePhoneRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.phone_number` | `string` | yes | The number to release, E.164. |
+| `body.provider` | `"twilio" \| "telnyx"` | yes | The carrier that holds it. It must match what the number was bought from - releasing a Telnyx number as `twilio` reaches the wrong provider. |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.phoneNumbers.releasePhoneNumber({ body: { phone_number: "+15555550100", provider: "twilio" } });
+```
+
+---
+
+<a id="op-resetvoicedailycounts"></a>
+
+### `g8.api.phoneNumbers.resetVoiceDailyCounts(input?)`
+
+**Reset today's per-number dialing counters**
+
+- HTTP: `DELETE /api/v1/voice/numbers/daily-counts`
+- operationId: `reset_voice_daily_counts_voice_numbers_daily_counts_delete` (also callable as `g8.api.call("reset_voice_daily_counts_voice_numbers_daily_counts_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `voice:delete`
+
+Clear today's outbound call counters for every number in this
+organisation.
+
+THIS REMOVES A CAP, it does not report on one. Each caller ID has a daily
+outbound limit (40 for US numbers, 60 international) that exists to keep
+carriers from flagging the number; resetting the counter lets those numbers
+dial past the limit they have already reached today.
+
+ADMIN-ONLY, and deliberately stricter than voice, which leaves this route
+ungated as an internal operations endpoint with no end-user caller. A
+customer-facing key that can quietly lift a carrier-reputation control is
+not something to publish on the same grant as renaming a number. Machine
+keys are refused outright.
+
+Counters reset on their own at midnight US Eastern. `deleted` is how many
+counter keys were actually cleared - zero is a normal answer for an
+organisation that has not dialled today.
+
+**Input**: none.
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.phoneNumbers.resetVoiceDailyCounts();
+```
+
+---
+
+<a id="op-savea2pinputs"></a>
+
+### `g8.api.phoneNumbers.saveA2pInputs(input)`
+
+**Save A2P brand and campaign details**
+
+- HTTP: `POST /api/v1/phone-numbers/a2p/inputs`
+- operationId: `save_a2p_inputs_phone_numbers_a2p_inputs_post` (also callable as `g8.api.call("save_a2p_inputs_phone_numbers_a2p_inputs_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `voice:write`
+
+Save the brand and campaign details WITHOUT submitting them.
+
+Nothing reaches a carrier and nothing is charged. This is the draft step -
+call it as often as you like, then submit once with `/a2p/register`.
+
+The save REPLACES what was there rather than merging, so send the whole
+object each time.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `A2pRegisterRequest` | yes | Request body; fields below. |
+
+Body fields (`A2pRegisterRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.brand_inputs` | `Record<string, unknown>` | no | The legal business behind the messages: `legal_business_name` (required before registration can start), plus `ein`, `address`, `website`, `business_type`, `vertical` and whatever else the carrier registry asks for. |
+| `body.campaign_inputs` | `Record<string, unknown>` | no | What the messages are: `use_case`, `message_samples` and `opt_in_method` are the three the platform checks for before it considers the inputs complete. |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.saveA2pInputs({ body: {} });
+```
+
+---
+
+<a id="op-searchavailablephonenumbers"></a>
+
+### `g8.api.phoneNumbers.searchAvailablePhoneNumbers(input)`
+
+**Search Available Phone Numbers**
+
+- HTTP: `POST /api/v1/phone-numbers/search`
+- operationId: `search_available_phone_numbers_phone_numbers_search_post` (also callable as `g8.api.call("search_available_phone_numbers_phone_numbers_search_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `voice:read`
+
+Numbers a carrier has available to buy. Buy one with `POST /phone-numbers/purchase`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PhoneNumberSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`PhoneNumberSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.provider` | `string` | yes | The carrier to search - the same values `POST /phone-numbers/purchase` takes. |
+| `body.area_code` | `string \| null` | no |  |
+| `body.country` | `string` | no | ISO country code. default `"US"` |
+| `body.locality` | `string \| null` | no | City. Use this or `pattern`, not both. |
+| `body.match` | `string` | no | Where `pattern` must appear: `first`, `anywhere` or `last`. default `"first"` |
+| `body.number_type` | `string` | no | `local` or `toll_free`. default `"local"` |
+| `body.pattern` | `string \| null` | no | Digits or a phrase the number must contain. |
+
+**Returns** `ApiResponse_PhoneNumberSearchPayload_`: the envelope `{ data: PhoneNumberSearchPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`PhoneNumberSearchPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.searchAvailablePhoneNumbers({ body: { provider: "example" } });
+```
+
+---
+
+<a id="op-starta2pregistration"></a>
+
+### `g8.api.phoneNumbers.startA2pRegistration(input)`
+
+**Submit A2P 10DLC registration**
+
+- HTTP: `POST /api/v1/phone-numbers/a2p/register`
+- operationId: `start_a2p_registration_phone_numbers_a2p_register_post` (also callable as `g8.api.call("start_a2p_registration_phone_numbers_a2p_register_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `voice:run`
+
+Submit the organisation to the US carrier registry. THIS REACHES A
+THIRD PARTY AND CARRIES CARRIER FEES.
+
+Saves the inputs, then starts a durable registration saga and returns its
+`workflow_id` immediately - registration takes days, not seconds, and the
+carriers can reject it. Without an approved registration, US carriers
+filter application-to-person SMS from these numbers, so this is not
+optional for messaging.
+
+IDEMPOTENT PER ORGANISATION: the workflow id is derived from the org, so a
+second call while one is running is a no-op rather than a second
+submission. Call `/a2p/inputs` first if you only want to save a draft.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `A2pRegisterRequest` | yes | Request body; fields below. |
+
+Body fields (`A2pRegisterRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.brand_inputs` | `Record<string, unknown>` | no | The legal business behind the messages: `legal_business_name` (required before registration can start), plus `ein`, `address`, `website`, `business_type`, `vertical` and whatever else the carrier registry asks for. |
+| `body.campaign_inputs` | `Record<string, unknown>` | no | What the messages are: `use_case`, `message_samples` and `opt_in_method` are the three the platform checks for before it considers the inputs complete. |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.phoneNumbers.startA2pRegistration({ body: {} });
+```
+
+---
+
+<a id="op-updatephoneassignee"></a>
+
+### `g8.api.phoneNumbers.updatePhoneAssignee(input)`
+
+**Reassign a phone number**
+
+- HTTP: `PATCH /api/v1/phone-numbers/update-assignee`
+- operationId: `update_phone_assignee_phone_numbers_update_assignee_patch` (also callable as `g8.api.call("update_phone_assignee_phone_numbers_update_assignee_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `voice:write`
+
+Move a number to a different person, and tell voice about it.
+
+Not a label: the assignee drives inbound ring targeting, missed-call
+notification and which numbers appear in that person's outbound caller-ID
+rotation pool.
+
+ADMIN-ONLY through this API. The app also accepts the number's current
+assignee or its creator, but an API key is an ORGANISATION credential with
+no `user_id`, so it can never be either - leaving it to fall through to the
+role check is what made this route 403 for every key before the role was
+supplied.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `UpdateAssigneeRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateAssigneeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.assignee` | `string` | yes | Who owns it now. This drives inbound ring targeting, missed-call notification and the outbound caller-ID pool - it is not a label. |
+| `body.phone_number` | `string` | yes | The number to reassign, E.164. |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.updatePhoneAssignee({ body: { assignee: "example", phone_number: "+15555550100" } });
+```
+
+---
+
+<a id="op-updatephonecapabilities"></a>
+
+### `g8.api.phoneNumbers.updatePhoneCapabilities(input)`
+
+**Switch a number between dialer and voice AI**
+
+- HTTP: `PATCH /api/v1/phone-numbers/update-capabilities`
+- operationId: `update_phone_capabilities_phone_numbers_update_capabilities_patch` (also callable as `g8.api.call("update_phone_capabilities_phone_numbers_update_capabilities_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `voice:write`
+
+Change what a number is for, and re-provision it to match.
+
+This reaches the voice platform: the LiveKit trunks and the carrier
+`voice_url` are re-pointed so inbound calls arrive where the new capability
+says they should. A number is briefly answering neither while that happens.
+
+The two flags are not independent. `dialer` set with `voice` unset means
+dialer; every other combination means voice AI - which is the app's own
+derivation, mirrored rather than reinvented.
+
+Admin-only for the same reason as `update-assignee`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `UpdateCapabilitiesRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateCapabilitiesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.phone_number` | `string` | yes | The number to reconfigure, E.164. |
+| `body.dialer` | `boolean` | no | Use the number for outbound dialing. default `false` |
+| `body.voice` | `boolean` | no | Answer inbound calls with a voice AI agent. default `false` |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.updatePhoneCapabilities({ body: { phone_number: "+15555550100" } });
+```
+
+---
+
+<a id="op-updatevoiceassignee"></a>
+
+### `g8.api.phoneNumbers.updateVoiceAssignee(input)`
+
+**Set a number's voice-side assignee**
+
+- HTTP: `PATCH /api/v1/voice/numbers/assignee`
+- operationId: `update_voice_assignee_voice_numbers_assignee_patch` (also callable as `g8.api.call("update_voice_assignee_voice_numbers_assignee_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `voice:write`
+
+Point a number's voice-side assignment at someone else.
+
+The VOICE half of `PATCH /phone-numbers/update-assignee`, which does this
+and updates the CDP record. Published separately because the app's
+propagation to voice is best-effort and only logs a warning when it fails -
+so the two records can disagree, and this is the way to reconcile them
+without re-running the whole reassignment.
+
+Sending `assigned_to: ""` clears the assignment. Assigning a WORK number
+also creates the person's phone-directory row, which is what makes them
+findable by name to the receptionist.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `VoiceAssigneeRequest` | yes | Request body; fields below. |
+
+Body fields (`VoiceAssigneeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.assigned_to` | `string` | yes | Email of the new assignee, or `""` to clear it. Normalised by voice before storage so inbound ring targeting, the dialer assignee filter and per-rep stat redaction all compare equal. |
+| `body.number` | `string` | yes | The number to reassign, E.164. |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.updateVoiceAssignee({ body: { assigned_to: "+15555550100", number: "example" } });
+```
+
+---
+
+<a id="op-updatevoiceinboundtype"></a>
+
+### `g8.api.phoneNumbers.updateVoiceInboundType(input)`
+
+**Change what answers a number's inbound calls**
+
+- HTTP: `PATCH /api/v1/voice/numbers/inbound-type`
+- operationId: `update_voice_inbound_type_voice_numbers_inbound_type_patch` (also callable as `g8.api.call("update_voice_inbound_type_voice_numbers_inbound_type_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `voice:write`
+
+Retype a number between AI answering, SDR answering and the dialer.
+
+NOT a label change, and not free. Moving to `dialer` DESTROYS the LiveKit
+dispatch rule and both SIP trunks and repoints the carrier webhook; moving
+away from it builds them again. The number answers nothing in between, and
+the teardown is best-effort - a failed trunk delete is logged and the
+retype continues.
+
+Retyping to the mode it is already in is a no-op, so this is safe to retry.
+
+Voice compares the number's own `org_id` against the one sent, and this
+route sends the API key's - so another organisation's number is a 404
+rather than a silent retype.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `VoiceInboundTypeRequest` | yes | Request body; fields below. |
+
+Body fields (`VoiceInboundTypeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.inbound_type` | `"ai" \| "sdr" \| "dialer" \| "work"` | yes | The answering mode to switch to. |
+| `body.number` | `string` | yes | The number to retype, E.164. |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.updateVoiceInboundType({ body: { inbound_type: "ai", number: "example" } });
+```
+
+---
+
+<a id="op-verifyvoicecallerid"></a>
+
+### `g8.api.phoneNumbers.verifyVoiceCallerId(input)`
+
+**Verify a Telnyx number as a caller ID**
+
+- HTTP: `POST /api/v1/voice/numbers/verify-caller-id/{phone_number}`
+- operationId: `verify_voice_caller_id_voice_numbers_verify_caller_id__phone_number__post` (also callable as `g8.api.call("verify_voice_caller_id_voice_numbers_verify_caller_id__phone_number__post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `voice:write`
+
+Start caller-ID verification for a Telnyx number.
+
+ONLY Telnyx numbers need this, and asking for a Twilio one is a 400 rather
+than a silent success - Twilio DIDs are valid callers by construction and
+have no verification record at all.
+
+Verification takes minutes, so this returns immediately with either
+`already_verified` or `verification_started`; poll
+`GET /voice/dialer/numbers` and read `caller_id_verified`. An unverified
+Telnyx number is a real number that simply cannot be dialled FROM, which is
+why it is kept out of the rotation pool rather than failing mid-session.
+
+Same ownership check as the delete above, for the same reason: voice looks
+the number up by bare value.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.phone_number` | `string` | yes | The number to verify, E.164. |
+
+**Returns** `ApiResponse_PhoneNumberPayload_`: the envelope `{ data: PhoneNumberPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.phoneNumbers.verifyVoiceCallerId({ path: { phone_number: "+15555550100" } });
+```