--- title: "Get a phone number" method: GET path: "/api/v1/numbers/{id}" tags: ["phoneNumbers"] --- # Get a phone number `GET /api/v1/numbers/{id}` Returns the number with its most recent messages and calls. ## Path parameters - `id` string, required ## Headers - `Authorization` string, required ## Response `200` The phone number. - PhoneNumbersGetNumberResponse200 - `number` PhoneNumber - `id` string - `number` string — The number in E.164 format. - `nickname` string, nullable — Optional human-readable label for the number, e.g. "Support line". Free text, at most 100 characters, not required to be unique. Null when unset. Set and cleared with Update a phone number. - `firstName` string, nullable — iMessage display first name — with `lastName` and the avatar photo, the identity shown beside this number's messages in recipients' Messages apps. At most 30 characters. Null when unset, and always null on numbers without the `imessage` capability. Set and cleared with Update a phone number. - `lastName` string, nullable — iMessage display last name. At most 30 characters. Null when unset, and always null on numbers without the `imessage` capability. Set and cleared with Update a phone number. - `avatarUrl` string, nullable — Public URL of the number's current iMessage avatar photo, hosted by Dial. Null when no photo has been set, and always null on numbers without the `imessage` capability. Set with Update a phone number; the photo can be replaced but not removed. - `country` string — ISO-3166-1 alpha-2 country code of the number. Always `US` — only US numbers can be provisioned at this time. - `capabilities` PhoneNumberCapabilitiesItems[] — Channels the number supports. `["sms","call"]` for a standard number; `["sms","call","imessage"]` for an iMessage number (which sends iMessage with automatic fallback to RCS/SMS). Mirrors the `capabilities` accepted when provisioning. - `setupStatus` 'provisioning' | 'ready' | 'failed' — Whether the number is ready to use. An SMS/call number is always `ready`. An `imessage` number is `provisioning` while it's being set up and only becomes usable for sending or calling once `ready` (`failed` on a setup error). Poll List phone numbers to await `ready`. - `setupError` string, nullable — Human-readable reason when `setupStatus` is `failed`; null otherwise. - `inboundInstruction` string, nullable — System prompt the AI voice agent uses on inbound calls to this number. Set at provisioning time and changeable with Update a phone number. Null for numbers provisioned before this field existed — those reject inbound calls until an instruction is set. - `inboundVoiceGender` 'male' | 'female' — Voice gender the AI agent uses on inbound calls to this number. Null when unset — the voice then uses the default, female. Set and cleared with Update a phone number. - `inboundLanguage` string, nullable — BCP-47 language tag the AI voice agent uses on inbound calls to this number. Null when unset — the language is then detected from the caller's country prefix on each call, with the agent handling both that language and `en-US`. Set and cleared with Update a phone number. - `accountId` string - `createdAt` string, date-time - `maxCallDurationSeconds` integer, nullable — Call-length cap in seconds; the effective cap on a call is the first one set in priority order — per-call, then number, then account — falling back to the global default. A higher-priority level overrides a lower one. Null means this level sets no cap. Free accounts (never added credit, never subscribed) are additionally hard-capped at 300 seconds regardless of any configured cap. - `tenDlc` PhoneNumberTenDlc — US 10DLC carrier registration for this number. Null when 10DLC does not apply to it — a non-US number, a number with the `imessage` capability (those send over Apple Messages for Business, not carrier SMS), or a number on an account that isn't pay-as-you-go and has no registration yet. Otherwise an object whose `status` says where the registration stands, starting at `not_registered`. US carriers block outbound SMS and MMS sent from an unregistered 10-digit number to US phone numbers. Registering lifts that block for this number. Inbound texts, voice calls in either direction, and messaging to numbers outside the US are unaffected. - `status` 'not_registered' | 'in_review' | 'with_carrier' | 'approved' | 'rejected', required — Where this number's registration stands. - `not_registered` — 10DLC applies to this number but nothing has been submitted. Outbound US SMS/MMS is blocked by carriers. - `in_review` — submitted; Dial is checking the details before filing them with the carrier registry. - `with_carrier` — filed with the carrier registry; a decision usually lands within 3–5 business days. - `approved` — registered. The number can send outbound SMS and MMS to US phone numbers. - `rejected` — changes are needed before it can be registered. See `reason`, then resubmit (no additional fee). The brand and the campaign are vetted separately, and this is the combined outcome: `approved` means both cleared, and `rejected` means either was turned down. - `kind` 'sole_proprietor' | 'business', required — Who the number was registered as. Null while `status` is `not_registered`. - `submittedAt` string, date-time, nullable, required — When the current submission was sent. Null while `status` is `not_registered`. A resubmission after a rejection updates this. - `reviewedAt` string, date-time, nullable, required — When the registration was approved or rejected. Null until then. - `reason` string, nullable, required — What needs to change, verbatim as shown to the account owner. Non-null only when `status` is `rejected`. ## Other responses - `401` — Missing or invalid API key. - `404` — The requested resource was not found on this account. --- [API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/versions/cfa621230237/schema)