Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Phone Number

With Twilio Proxy, you associate phone numbers (this resource) and short codes directly with a Proxy Service. All added numbers go into the Phone Number Pool associated with a given Proxy Service. For more information on managing the phone numbers in your phone number pool, refer to our Phone Number Management guide.

Note on Phone Numbers associated with Services

A Twilio number associated with a Proxy Service cannot be associated with other Proxy Services in the same account, nor should it be associated with a Messaging Service.

In a Proxy service, phone numbers can be marked as Reserved. Reserved numbers will not be included in the set of numbers Proxy considers when choosing a number for a participant, but they can be manually assigned as Proxy Numbers for participants (e.g., in a lead tracking use-case).

Phone Number Pools are limited to 5000 reserved phone numbers and 500 unreserved phone numbers per Proxy Service. Numbers can be distributed across multiple Proxy Services if you need more of numbers.

PhoneNumber properties

Resource Properties in REST API format
sid
sid<PN> Not PII

The unique string that we created to identify the PhoneNumber resource.

account_sid
sid<AC> Not PII

The SID of the Account that created the PhoneNumber resource.

service_sid
sid<KS> Not PII

The SID of the PhoneNumber resource's parent Service resource.

date_created
date_time<iso8601> Not PII

The ISO 8601 date and time in GMT when the resource was created.

date_updated
date_time<iso8601> Not PII

The ISO 8601 date and time in GMT when the resource was last updated.

phone_number
phone_number Not PII

The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.

friendly_name
string Not PII

The string that you assigned to describe the resource.

iso_country
string Not PII

The ISO Country Code for the phone number.

capabilities
phone_number_capabilities Not PII

The capabilities of the phone number.

url
url Not PII

The absolute URL of the PhoneNumber resource.

is_reserved
boolean Not PII

Whether the phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers for more information.

in_use
integer Not PII

The number of open session assigned to the number. See the How many Phone Numbers do I need? guide for more information.

Add a Phone Number to a Proxy Service

post
https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers
Parameters
Parameters in REST API format
service_sid
Path
post sid<KS> Not PII

The SID parent Service resource of the new PhoneNumber resource.

sid
Optional
post sid<PN> Not PII

The SID of a Twilio IncomingPhoneNumber resource that represents the Twilio Number you would like to assign to your Proxy Service.

phone_number
Optional
post phone_number Not PII

The phone number in E.164 format. E.164 phone numbers consist of a + followed by the country code and subscriber number without punctuation characters. For example, +14155551234.

is_reserved
Optional
post boolean Not PII

Whether the new phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers for more information.

Example 1
        
        
        
        
        Example 2
              
              
              
              

              Note: You should pass a PhoneNumber or a Sid (identifying a phone number on your account). Only one of them is required. Passing both will return an error.

              Fetch a PhoneNumber resource

              get
              https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers/{Sid}
              Parameters
              Parameters in REST API format
              service_sid
              Path
              get sid<KS> Not PII

              The SID of the parent Service of the PhoneNumber resource to fetch.

              sid
              Path
              get sid<PN> Not PII

              The Twilio-provided string that uniquely identifies the PhoneNumber resource to fetch.

              Example 1
                    
                    
                    
                    

                    Get the list of Phone Numbers associated with a Proxy Service

                    get
                    https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers
                    Parameters
                    Parameters in REST API format
                    service_sid
                    Path
                    get sid<KS> Not PII

                    The SID of the parent Service of the PhoneNumber resources to read.

                    Example 1
                          
                          
                          
                          

                          Update a PhoneNumber resource

                          post
                          https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers/{Sid}
                          Parameters
                          Parameters in REST API format
                          service_sid
                          Path
                          post sid<KS> Not PII

                          The SID of the parent Service of the PhoneNumber resource to update.

                          sid
                          Path
                          post sid<PN> Not PII

                          The Twilio-provided string that uniquely identifies the PhoneNumber resource to update.

                          is_reserved
                          Optional
                          post boolean Not PII

                          Whether the phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers for more information.

                          Example 1
                                
                                
                                
                                

                                Remove a Phone Number from a Proxy Service

                                delete
                                https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers/{Sid}
                                Parameters
                                Parameters in REST API format
                                service_sid
                                Path
                                delete sid<KS> Not PII

                                The SID of the parent Service of the PhoneNumber resource to delete.

                                sid
                                Path
                                delete sid<PN> Not PII

                                The Twilio-provided string that uniquely identifies the PhoneNumber resource to delete.

                                Example 1
                                      
                                      
                                      
                                      
                                      Rate this page:

                                      Need some help?

                                      We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.