Twilio's REST API is organized around a single account namespace. Nearly every resource is owned by an account and most endpoints require an AccountSid (format AC...) in the path. Other frequently required resource IDs follow stable SID prefixes that reveal their type: CA... (Call), PN... (Phone Number / Outgoing Caller ID), RE... (Recording), CF... (Conference), QU... (Queue), CL... (Credential List), SD... (SIP Domain), SK... (Key / Signing Key), UT... (Usage Trigger), XR... / XH... (Recording Add-on results/payloads), and so on. Recognize these prefixes: they tell you which operations expect which identifier and how resources relate to each other.

How the domain fits together

Accounts are the top-level scope. Most operations act against an account and then against a resource owned by that account (calls, messages, incoming phone numbers, recordings, conferences, SIP domains, queues, usage records, etc.). Many resources are hierarchical: for example, a Call (CallSid) contains Recordings, Streams, Transcriptions, Payments sessions and User Defined Messages; a Conference (ConferenceSid) contains Participants and Conference Recordings; an Incoming Phone Number (PN...) can have assigned Add-ons and Add-on Extensions.

Two practical consequences: when a user asks to act on a resource you must (1) identify the owning AccountSid and (2) obtain the resource's SID from the appropriate list or fetch endpoint before invoking operations that require it.

Entry points — what to call first

Start with these calls to obtain the IDs other operations need or to discover available actions for a user request:

• ListAccount or FetchAccount to enumerate the master account and subaccounts and get their AccountSids and friendly names. Subaccounts are real accounts; many operations must be called against the owning account.
• ListIncomingPhoneNumber to list owned numbers and their Sid (PN...). Use this when a user references "my Twilio numbers" or you need a From to send an SMS or make a call.
• The family of ListAvailablePhoneNumber* endpoints to search numbers to buy (local, mobile, toll-free, VOIP, etc.). They return candidate numbers you buy with CreateIncomingPhoneNumber*.
• ListMessage / FetchMessage for message histories; CreateMessage to send SMS/MMS. ListMedia / FetchMedia for attached media.
• ListCall / FetchCall for calls; CreateCall to place an outbound call. From a CallSid you can manage recordings, streams, real-time transcription, payments, and user-defined messages.
• ListConference / FetchConference and ListParticipant / FetchParticipant for conferences and their participants; CreateParticipant to add someone.
• ListRecording / FetchRecording and the recording add-on/result endpoints when you need post-processing artifacts.
• ListUsageRecord* and ListUsageTrigger to inspect billing/usage and to work with alerts.

These are the practical discovery steps that resolve the SIDs required by the many resource-level operations throughout the API.

Common user tasks and the call sequences to perform them

Below are the typical tasks users ask the assistant to perform and the logical sequence of operations to complete each.

Send an SMS or MMS

• Ensure you have a Twilio From number: call ListIncomingPhoneNumber to select a PN... you own. If they need a new number, search with ListAvailablePhoneNumber* then buy with CreateIncomingPhoneNumber*.
• Create the outgoing message with CreateMessage (specify From, To, message content, and media as needed).
• Inspect delivery or content with FetchMessage or ListMessage. To remove sensitive content use UpdateMessage (supports redaction/cancellation behaviors).

Purchase a phone number

• Use the appropriate ListAvailablePhoneNumber* (local/mobile/toll-free/voip) with filters (region, capabilities, near-number) to find candidates.
• If a chosen number requires an address (some geographic numbers do), create an Address (CreateAddress) in the owning account first and then pass the address reference when purchasing.
• Purchase with CreateIncomingPhoneNumber or the type-specific CreateIncomingPhoneNumberLocal/Mobile/TollFree.
• After purchase, call FetchIncomingPhoneNumber to confirm the PN... and then CreateIncomingPhoneNumberAssignedAddOn if you need to assign add-ons.

Place and manage calls

• Create an outbound call with CreateCall (specify From and To). The response includes the CallSid (CA...).
• To redirect or end a live call, use UpdateCall on the CallSid (redirect, hang up, or change TwiML URL).
• To record: create recordings tied to a call with CreateCallRecording; list them with ListCallRecording and fetch with FetchCallRecording. You can pause/stop recordings via UpdateCallRecording; you can also reference Twilio.CURRENT in recording-level updates to target the active recording.
• For real-time streaming or transcription: CreateStream / CreateRealtimeTranscription and stop via UpdateStream / UpdateRealtimeTranscription (you can use the SID or the name, and Twilio.CURRENT works for active resources).
• For payment flows tied to a call: CreatePayments to start a payments session (call-scoped) and UpdatePayments to progress its phases. Those endpoints require the CallSid and return a payments session PK....

Recordings, add-ons, and post-processing

• Recordings have a soft-delete retention window: recording metadata is kept after deletion for a retention period (commonly noted as 40 days). Use the IncludeSoftDeleted flag when fetching a recording if you need metadata for recently deleted recordings.
• Add-on results for recordings are hierarchical: ListRecordingAddOnResult (for a recording RE...), then ListRecordingAddOnResultPayload and FetchRecordingAddOnResultPayload for payloads and their data.

Conferences and participants

• Manage conferences with ListConference, FetchConference, UpdateConference.
• Participants are identified by their conference and either their CallSid or a label. Use ListParticipant/FetchParticipant to inspect them, CreateParticipant to add, UpdateParticipant to change attributes (mute/hold/coaching), and DeleteParticipant to remove (kick).
• When a participant is referenced by label (not Call SID), supply the exact label used by the conference UI.

SIP, credential lists, and domains

• SIP resources are namespaced under AccountSid and DomainSid (SD...). Create and manage SIP domains (CreateSipDomain / ListSipDomain), credential lists (CreateSipCredentialList / ListSipCredentialList / CreateSipCredential), IP ACLs (CreateSipIpAccessControlList), and their mappings. Many operations require the DomainSid to scope mappings.

Keys, signing keys, and signing-related items

• Create keys with CreateNewKey / CreateNewSigningKey; list and fetch them with ListKey / FetchKey / ListSigningKey / FetchSigningKey. Delete with DeleteKey / DeleteSigningKey. These SIDs are SK....

Usage and billing

• Usage queries are split by granularity (ListUsageRecordToday, ...ThisMonth, ...Monthly, ...Yearly, and top-level ListUsageRecord). Use IncludeSubaccounts when you need rollups across master + subaccounts. For long-term or aggregated views, choose the All-Time or Monthly variants as appropriate.

Important non-obvious behaviors and gotchas

Account scope and subaccounts

• Account scope matters: most endpoints require the owning AccountSid. If the user has multiple subaccounts, list accounts to determine the correct AccountSid for the resource you must act on. Child accounts do not contain balance info—use the master account when you need the consolidated balance.

Identifiers and where to get them

• SID prefixes indicate resource type and which operations expect them. When a user gives a human-visible name or phone number, first translate that to the resource SID via the appropriate list endpoint (for example, call ListIncomingPhoneNumber to find the PN... for a given phone number).
• Participant references in conference endpoints accept either a CallSid or a participant label; provide the exact label as shown in the conference context when the user references a label.

Active resources: use the special reference values

• For some recording/stream/transcription operations you can target the currently active resource with Twilio.CURRENT rather than a SID. This is useful when you need to pause/stop the active recording/stream without first listing and selecting the recording SID.

Recordings and deletion

• Recording metadata is retained for a short retention window after deletion. If you need metadata of a recently-deleted recording, pass the flag to include soft-deleted recordings on fetch/list operations.

Phone-number purchase and address requirements

• Some geographic numbers require an Address resource before purchase. If ListAvailablePhoneNumber* returns numbers that require an address, create an Address in the same account and then purchase the number.

Search vs buy: available-number filters

• Searching numbers offers many filters (near a number, within distance, area code, capabilities like SMS/MMS/Voice/Fax). Use the appropriate ListAvailablePhoneNumber* variant for the number type (local, mobile, toll-free, VOIP, machine-to-machine, shared-cost, national).

Message lifecycle

• Messages can be canceled or redacted via UpdateMessage—use this when removing sensitive content or aborting queued messages. Deleting a Message removes it from the account.

Add-ons and extensions

• Phone numbers support Add-on installations and per-installation extensions. The flow is: list assigned add-ons, assign with CreateIncomingPhoneNumberAssignedAddOn, then manage extensions under the assigned add-on. Add-on result payloads are hierarchical and require the recording reference SID and the add-on result SID to fetch their payloads.

SIP domain mappings and multi-level SIDs

• SIP configuration operations are nested: domain-scoped mappings require both the account AccountSid and the DomainSid (SD...). When working with credential list mappings or IP ACL mappings, get the domain's SD... first.

Usage triggers

• Usage triggers are account-scoped (UT...) and can be recurring; create, update, list and delete them with the usage-trigger endpoints. Check the trigger fields when creating so the trigger fires on the intended usage category and threshold.

Parameters that commonly appear but differ in meaning

• Many list endpoints expose PageSize, Page, and PageToken—use them to control result page size and pagination state. Several list endpoints accept date filters where inequalities (<=, >=) are expressed as variant parameter names—read the operation's arguments when you need a date-range query.

When you need to inspect an operation's shape

Operation signatures include the path parameters and the request body fields for creation and update calls. When a user asks for a specific change (for example, "move this phone number to a subaccount" or "start a payment and collect card details via DTMF"), first resolve the required SIDs (account, call, phone number) using the list/fetch entry points above, then invoke the create/update operation for that resource. Look up the operation's request-body fields only when you already have the SIDs and know which resource to change.

Prioritize these actions for common user requests

• Send SMS/MMS: CreateMessage after choosing a PN... from ListIncomingPhoneNumber (or buying with CreateIncomingPhoneNumber*).
• Place or redirect calls: CreateCall then UpdateCall as needed; use CreateCallRecording / UpdateCallRecording and CreateStream / UpdateStream for media/transcription control.
• Buy numbers: ListAvailablePhoneNumber* → CreateIncomingPhoneNumber*; create an Address first if required.
• Conferencing: ListConference / CreateParticipant / UpdateParticipant / DeleteParticipant.
• Recordings and add-ons: ListRecording → ListRecordingAddOnResult → payload endpoints.
• Billing/usage: the set of ListUsageRecord* endpoints for the granularity required and ListUsageTrigger to inspect or create alerts.

Use the resource hierarchy and SID prefixes as your mental map. Resolve the owning AccountSid and the immediate parent resource (Call, Conference, Recording, Phone Number, Domain) before calling the resource-level operation that performs the user's requested action.