Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

Twilio's REST surface in this collection centers on a small set of core entities and predictable identifier patterns. Accounts (SIDs starting with AC) are the top-level scope most operations require. Under an account you manage phone-related resources: Addresses (AD SIDs), Applications (AP SIDs), Calls (CA SIDs), and objects related to phone numbers and connect apps (CN, BY, etc.). Treat the Account SID as the primary scoping key: nearly every read, create, update, or delete operation for resources in this collection requires an AccountSid or an account Sid parameter.

Key entities and how they relate

  • Accounts (AC...) are the root scope. Subaccounts are ordinary Account resources created with CreateAccount and returned by ListAccount.
  • Addresses (AD...) live under an account and are used for emergency/regulatory compliance and associating location metadata with numbers.
  • Applications (AP...) are lightweight handlers that encapsulate URLs/TwiML settings for voice and SMS; phone numbers and calls can reference an ApplicationSid so Twilio invokes the stored behavior instead of using inline Url/Twiml fields.
  • Calls (CA...) are created under an account and can reference an ApplicationSid, a Url, or inline Twiml to drive call behavior. Calls may also reference BYOC trunks (BY...) and Connect Apps (CN...) in some parameters.
  • Available phone number searches are returned by country-specific list operations (local, mobile, toll-free, voip, etc.). These operations return available_phone_numbers collections that you typically use as search input before purchasing a number (purchasing is a separate IncomingPhoneNumbers create operation, not listed here).

Understanding these relations prevents dead-ends: create or locate an AccountSid first, then list or create address/application/phone-number resources under that account, then create calls or associate numbers that reference those resource SIDs.

Identifier patterns that matter

These prefixes appear repeatedly and tell you what a value is without extra lookup:

  • AC... — Account SID (primary scope). Many operations accept either an explicit AccountSid path parameter or an account Sid for updates/fetches.
  • AP... — Application SID. Pass this to calls to have the Application handle voice/SMS webhooks; when present many call parameters are ignored (see gotchas).
  • AD... — Address SID.
  • CA... — Call SID.
  • CN... — Connect App SID (authorized connect apps).
  • BY... — BYOC trunk SID.

If a user gives a plain phone number or a resource URL, extract the Account SID first (or call FetchAccount/ListAccount) so subsequent operations are scoped correctly.

Where to start (entry points)

Start by confirming which account to act on. Use one of these first depending on the user's intent:

  • To act on the authenticated account or to confirm its properties, call FetchAccount. The returned Sid and subresource_uris let you scope follow-up calls.
  • To operate across subaccounts, call ListAccount to enumerate child accounts and pick an AC... to use as AccountSid.
  • To check spendability or fund availability, call FetchBalance with an AccountSid. Note: child accounts do not contain balance info.
  • To search for phone numbers for purchase, call ListAvailablePhoneNumberCountry first to discover the country code metadata, then call the appropriate country-specific number-list operation (ListAvailablePhoneNumberLocal, ...Mobile, ...TollFree, ...Voip, etc.). Those list operations return available_phone_numbers you can present to a user.

Most follow-up operations require that AccountSid value; resolve it up front so you can pass it to CreateCall, CreateAddress, CreateApplication, and the other create/update/delete operations.

Common tasks and the minimal sequence of calls

Below are the typical workflows users ask for and the operations you will call, in order.

Make an outbound phone call

  • Ensure you have an AccountSid. If you need to confirm it, call FetchAccount.
  • Create the call with CreateCall. Required inputs are To and From. Provide either an ApplicationSid or a Url/Twiml that supplies TwiML for call handling.
  • Observe the returned call resource to get Sid (CA...) and status. Deleting a call record uses DeleteCall but note deletion removes the record from logs.

Notes about call parameters (non-obvious):

  • If you pass ApplicationSid, Twilio prefers the application’s stored settings and ignores several per-call URL parameters (for example, Method, FallbackUrl, FallbackMethod, StatusCallback, StatusCallbackEvent, and StatusCallbackMethod are ignored when an application is present). Use an ApplicationSid when you want consistent behavior managed centrally; use Url/Twiml for one-off behavior.
  • If you supply both Url and Twiml, the Twiml parameter will be ignored — provide only the one you intend to be primary.
  • SendDigits and answering-machine detection interact: if SendDigits is provided, MachineDetection will be ignored. Specify only the behavior you expect.
  • AsyncAmd controls whether answer‑machine detection runs in the background. By default AMD can block call flow; set AsyncAmd to run detection asynchronously when you do not want the call to wait for detection to finish.
  • Byoc (a BY... SID) is only meaningful when To is a phone number; it will be ignored for other To targets (SIP, client IDs).
  • Use CallToken only when forwarding an incoming call and you want to preserve the original incoming caller details; a call_token is produced from an incoming call event and must be passed to the forwarded outgoing call.

Create and manage Applications

  • Create an application with CreateApplication and identify it by the returned Sid (AP...) and FriendlyName.
  • List applications with ListApplication to find SIDs for reuse. Update with UpdateApplication and remove with DeleteApplication.
  • Applications centralize webhook URLs for voice and SMS; reference an ApplicationSid from calls or phone numbers to inherit those settings.

Manage Address resources (emergency/regulatory)

  • Create addresses with CreateAddress. Addresses require full postal fields plus IsoCountry and may need EmergencyEnabled for emergency-address use cases.
  • List, fetch, update, and delete an address with ListAddress, FetchAddress, UpdateAddress, DeleteAddress respectively.

Address nuances to remember:

  • FriendlyName length differs by use: Regulatory Compliance addresses allow up to 64 characters; Emergency addresses only allow up to 32 characters. Pick the appropriate length based on whether the address will be used for emergency E911.
  • AutoCorrectAddress defaults to true; set it to false only when you must preserve the exact submitted address.

Search available phone numbers

  • Call ListAvailablePhoneNumberCountry to get country-level metadata (and confirm supported types), then call the country-specific list operation for the type you need (Local, Mobile, TollFree, Voip, SharedCost, National, or MachineToMachine).
  • Those search endpoints return available_phone_numbers. Use them to present options and then create an IncomingPhoneNumber resource to purchase (purchase/create is not included in this operation list but is the usual next step).

Account-level management

  • Create a subaccount with CreateAccount when a user asks to segregate resources or billing; list accounts with ListAccount to find and act on subaccounts.
  • Update an account's FriendlyName or Status with UpdateAccount and fetch account details with FetchAccount.
  • Use FetchBalance for monetary info; remember child accounts do not have balance data.

Authorized Connect Apps

  • List authorized connect apps with ListAuthorizedConnectApp and fetch a specific connect app with FetchAuthorizedConnectApp using the ConnectAppSid (CN...). These are account-level and do not nest under other resources.

Non-obvious behaviors and gotchas

  • Account-first mindset: almost every operation requires an account Sid (AC...). If a user gives resource identifiers but no account, locate or confirm the account Sid before attempting create/update/delete calls.
  • Resource prefixes are meaningful: you can usually tell the resource type by its SID prefix and use that to route the next operation.
  • Call parameter precedence and ignored fields: when an ApplicationSid is present, per-call URL and callback parameters are ignored. When both Twiml and Url are given, Twiml is ignored. When SendDigits is provided, MachineDetection is ignored. These conflicts are the most common source of surprises when callers expect per-call overrides to take effect.
  • Balance visibility: FetchBalance does not return balances for child/subaccounts.
  • Deleting call records: DeleteCall permanently removes a call record from the API/logs—do not delete if the user expects to retain historical logs.
  • Address FriendlyName length differs by purpose (regulatory vs emergency); supply a shorter name for emergency addresses.
  • BYOC (BY...) values and Byoc parameters are ignored unless To is a PSTN phone number.
  • Answering-machine detection complexity: MachineDetection has multiple modes and several tuning parameters (MachineDetectionTimeout, speech thresholds, silence thresholds). If you want immediate AnsweredBy values prefer the appropriate MachineDetection mode; if you want the call to proceed immediately and get detection results later, use AsyncAmd and a status callback.

What to look for in responses

  • Resource creation responses include the new resource SID (e.g., AP..., AD..., CA...); capture that SID to perform updates, deletes, or further associations.
  • List responses return paginated envelopes with first_page_uri, next_page_uri, and a page_size field. If you need more results than fit in a page, request subsequent pages using the list parameters.
  • FetchAccount and other fetch operations return the canonical SIDs and subresource URIs that help navigate the account's resources.

Follow these patterns and you can reliably: choose the correct account scope, create or locate applications and addresses, search numbers, place calls with the behavior you expect, and manage the returned resources by their SIDs. When a user asks for an action that requires a resource SID you don't yet have, get or create the scoped resource first and use its SID in the next operation.