Managing Phone Numbers

Find and purchase a phone number, configure its messaging and voice callbacks, and manage it throughout its lifecycle.

Before you begin

Use your TextGrid Account SID and Auth Token as described in Getting Started with TextGrid. Send the Base64-encoded literal AccountSid:AuthToken pair in your Authorization header:

Authorization: Bearer YOUR_BASE64_ENCODED_CREDENTIALS

All paths below are relative to:

https://api.textgrid.com/2010-04-01

Phone numbers and identifiers in the examples are fictitious. Replace them with your own values. Purchasing a number is a billable operation; review your account's pricing and ensure the account has the required permissions and balance.

1. Search for an available number

Search available local numbers for a country, optionally filtering by area code:

GET /Accounts/YOUR_ACCOUNT_SID/AvailablePhoneNumbers/US/Local.json?areaCode=202

Use the supported ISO country code in the path.

Review each result's phone_number and capabilities to select a number suited to your messaging or voice requirements. Capability fields include sms, mms, and voice.

A search result does not reserve the number. Availability can change before purchase.

2. Purchase the number

Send a POST request to:

POST /Accounts/YOUR_ACCOUNT_SID/IncomingPhoneNumbers.json
Content-Type: application/x-www-form-urlencoded

Supply these form fields:

Field	Example value
`phoneNumber`	`+12025550100`
`friendlyName`	`Customer Support`

These are form fields, not a JSON body. Use your HTTP client's form encoder so the leading + in the phone number is encoded as %2B, rather than interpreted as a space.

You can also configure callback URLs, HTTP methods, and other number settings in the purchase request, without making a separate update request. See the Add Incoming Phone Number endpoint in the API Reference for all available configuration options.

On success, save the returned sid. This is the phone-number SID, which you use to retrieve or update the number and attach it to a campaign. It is distinct from the phone_number value you use as a message sender or calling number.

3. List and retrieve your numbers

List numbers on your account:

GET /Accounts/YOUR_ACCOUNT_SID/IncomingPhoneNumbers.json?Page=0&PageSize=50

Page is zero-based. The default PageSize is 50.

Retrieve a particular number using its SID:

GET /Accounts/YOUR_ACCOUNT_SID/IncomingPhoneNumbers/YOUR_PHONE_NUMBER_SID.json

Useful response fields include sid, phone_number, friendly_name, capabilities, and the configured callback URLs and methods. Null fields can be omitted.

4. Configure messaging and voice callbacks

Update a number using POST:

POST /Accounts/YOUR_ACCOUNT_SID/IncomingPhoneNumbers/YOUR_PHONE_NUMBER_SID.json
Content-Type: application/x-www-form-urlencoded

Submit the applicable form fields:

Field	Purpose	Example value
`friendlyName`	Your label for the number.	`Customer Support`
`smsUrl`	Endpoint for incoming SMS and MMS.	`https://example.com/webhooks/messages`
`smsMethod`	HTTP method for incoming-message callbacks.	`POST`
`voiceUrl`	Endpoint that returns instructions for incoming calls.	`https://example.com/voice/instructions`
`voiceMethod`	HTTP method for incoming call instructions.	`POST`
`statusCallback`	Number-level status callback URL.	`https://example.com/webhooks/status`
`statusCallbackMethod`	HTTP method for number-level status callbacks.	`POST`

The number-level statusCallback can receive messaging delivery notifications and incoming-call final status notifications. Route events appropriately if the number supports both messaging and voice. A message's own statusCallback takes precedence over the number-level setting for that message. Outgoing calls use the StatusCallback supplied when creating the call.

For GET callbacks, fields appear in the query string. For POST callbacks, messaging and voice fields are sent as application/x-www-form-urlencoded.

Forward incoming calls

You can configure a phone number to forward incoming calls to another phone number. When forwarding is enabled, TextGrid connects incoming calls to the configured destination instead of requesting instructions from the number's voiceUrl. Your incoming voice instructions webhook will not be called, even if a voiceUrl is configured.

Disable call forwarding when you want your application to handle incoming calls through the voice instructions webhook. Your webhook can then return greetings, keypad menus, or TwiML Dial instructions to route calls. See Receiving Voice Calls.

Respond to each callback appropriately

Incoming messages: Follow the acknowledgment and supported reply behavior in Messaging Webhooks.
Incoming call instructions: Return TwiML XML as described in Voice Webhooks.
Status notifications: Record the result and return an accepted acknowledgment; do not treat them as requests for call instructions.

Verify X-TextGrid-Signature using your account's Webhook Secret before processing callbacks. See Verifying Webhook Signatures.

The API also exposes messaging and voice fallback URL and method settings. Their presence does not imply identical retry or fallback behavior across callback types; use the behavior documented for each webhook.

After updating a number, retrieve it again to confirm its configuration, then test your callbacks with your application.

5. Complete messaging registration

Purchasing a number does not by itself enable campaign traffic. For traffic requiring 10DLC registration, complete brand and campaign approval and attach the number to the campaign using its phone-number SID.

Attachment is not instant. It usually completes within a few minutes, but can take up to a few days, especially over a weekend or legal holiday. Wait for attachment to complete before sending campaign traffic.

See 10DLC Registration for the full workflow, registration charges, and attachment checks.

Once the number is ready, follow Sending SMS and MMS or Making Voice Calls to use it.

Release a number

When you no longer need a number, release it using:

DELETE /Accounts/YOUR_ACCOUNT_SID/IncomingPhoneNumbers/YOUR_PHONE_NUMBER_SID.json

Releasing a number removes it from your account. Stop using it in sending workflows and update any application settings that reference it before release. Do not assume you can acquire the same number again later.

Detaching a number from a 10DLC campaign is a separate operation and does not release the number from your account.

Handle errors and uncertain requests

Check the HTTP status and response body. Account restrictions, insufficient balance, number availability, and provider validation can prevent an operation from succeeding. Error bodies vary and can be empty.

If a purchase request times out before you receive a response, check your account's number list before retrying. The purchase may already have succeeded; submitting another area-code purchase request could acquire an additional number and incur additional charges.