<commit_before>.. module:: twilio.rest.resources

=================
Phone Numbers
=================

With Twilio you can search and buy real phones numbers, just using the API.

For more information, see the `IncomingPhoneNumbers REST Resource <http://www.twilio.com/docs/api/rest/incoming-phone-numbers>`_ documentation.


Searching and Buying a Number
--------------------------------

Finding numbers to buy couldn't be easier. We first search for a number in area code 530. Once we find one, we'll purchase it for our account.

.. code-block:: python

    from twilio.rest import TwilioRestClient

    # To find these visit https://www.twilio.com/user/account
    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
    AUTH_TOKEN = "<PASSWORD>"

    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
    numbers = client.phone_numbers.search(area_code=530)

    if numbers:
        numbers[0].purchase()
    else:
        print "No numbers in 530 available"

Toll Free Numbers
^^^^^^^^^^^^^^^^^^^^^^^^

By default, :meth:`search` looks for local phone numbers. Set :data:`type` to
``tollfree`` to search toll-free numbers instead.

.. code-block:: python

    numbers = client.phone_numbers.search(type="tollfree")


Numbers Containing Words
^^^^^^^^^^^^^^^^^^^^^^^^^^

Phone number search also supports looking for words inside phone numbers. The following example will find any phone number with "FOO" in it.

.. code-block:: python

    numbers = client.phone_numbers.search(contains="FOO")

You can use the ''*'' wildcard to match any character. The following example finds any phone number that matches the pattern ''D*D''.

.. code-block:: python

    numbers = client.phone_numbers.search(contains="D*D")

:meth:`PhoneNumbers.search` method has plenty of other options
to augment your search. The `AvailablePhoneNumbers REST Resource
<http://www.twilio.com/docs/api/rest/available-phone-numbers>`_ documentation
also documents the various search options.


Buying a Number
---------------

If you've found a phone number you want, you can purchase the number.

.. code-block:: python

    from twilio.rest import TwilioRestClient

    # To find these visit https://www.twilio.com/user/account
    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
    AUTH_TOKEN = "<PASSWORD>"

    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
    number = client.phone_numbers.purchase("+15305431234")

However, it's easier to purchase numbers after finding them using search (as shown in the first example).


Changing Applications
----------------------

An :class:`Application` encapsulates all necessary URLs for use with phone numbers. Update an application on a phone number using :meth:`update`.

.. code-block:: python

    from twilio.rest import TwilioRestClient

    phone_sid = "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

    # To find these visit https://www.twilio.com/user/account
    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
    AUTH_TOKEN = "<PASSWORD>"

    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
    number = client.phone_numbers.update(phone_sid, application="AP123")

See :doc:`/usage/applications` for instructions on updating and maintaining Applications.

Validate Caller Id
-----------------------
Twilio Adding a new phone number to your validated numbers is quick and easy

.. code-block:: python

    from twilio.rest import TwilioRestClient

    # To find these visit https://www.twilio.com/user/account
    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
    AUTH_TOKEN = "<PASSWORD>"

    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
    response = client.caller_ids.validate("+9876543212")
    print response["validation_code"]

Twilio will call the provided number and wait for the validation code to be
entered.

<commit_msg>Fix documentation error relating to phone number purchasing<commit_after>.. module:: twilio.rest.resources

=================
Phone Numbers
=================

With Twilio you can search and buy real phones numbers, just using the API.

For more information, see the `IncomingPhoneNumbers REST Resource <http://www.twilio.com/docs/api/rest/incoming-phone-numbers>`_ documentation.


Searching and Buying a Number
--------------------------------

Finding numbers to buy couldn't be easier. We first search for a number in area code 530. Once we find one, we'll purchase it for our account.

.. code-block:: python

    from twilio.rest import TwilioRestClient

    # To find these visit https://www.twilio.com/user/account
    ACCOUNT_SID = "AC<KEY>XXXXXXXXX"
    AUTH_TOKEN = "<PASSWORD>"

    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
    numbers = client.phone_numbers.search(area_code=530)

    if numbers:
        numbers[0].purchase()
    else:
        print "No numbers in 530 available"

Toll Free Numbers
^^^^^^^^^^^^^^^^^^^^^^^^

By default, :meth:`search` looks for local phone numbers. Set :data:`type` to
``tollfree`` to search toll-free numbers instead.

.. code-block:: python

    numbers = client.phone_numbers.search(type="tollfree")


Numbers Containing Words
^^^^^^^^^^^^^^^^^^^^^^^^^^

Phone number search also supports looking for words inside phone numbers. The following example will find any phone number with "FOO" in it.

.. code-block:: python

    numbers = client.phone_numbers.search(contains="FOO")

You can use the ''*'' wildcard to match any character. The following example finds any phone number that matches the pattern ''D*D''.

.. code-block:: python

    numbers = client.phone_numbers.search(contains="D*D")

:meth:`PhoneNumbers.search` method has plenty of other options
to augment your search. The `AvailablePhoneNumbers REST Resource
<http://www.twilio.com/docs/api/rest/available-phone-numbers>`_ documentation
also documents the various search options.


Buying a Number
---------------

If you've found a phone number you want, you can purchase the number.

.. code-block:: python

    from twilio.rest import TwilioRestClient

    # To find these visit https://www.twilio.com/user/account
    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
    AUTH_TOKEN = "<PASSWORD>"

    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
    number = client.phone_numbers.purchase("+15305431234")

However, it's easier to purchase numbers after finding them using search (as shown in the first example).


Changing Applications
----------------------

An :class:`Application` encapsulates all necessary URLs for use with phone numbers. Update an application on a phone number using :meth:`update`.

.. code-block:: python

    from twilio.rest import TwilioRestClient

    phone_sid = "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

    # To find these visit https://www.twilio.com/user/account
    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
    AUTH_TOKEN = "<PASSWORD>"

    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
    number = client.phone_numbers.update(phone_sid, application_sid="AP123")

See :doc:`/usage/applications` for instructions on updating and maintaining Applications.

Validate Caller Id
-----------------------
Twilio Adding a new phone number to your validated numbers is quick and easy

.. code-block:: python

    from twilio.rest import TwilioRestClient

    # To find these visit https://www.twilio.com/user/account
    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
    AUTH_TOKEN = "<PASSWORD>"

    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
    response = client.caller_ids.validate("+9876543212")
    print response["validation_code"]

Twilio will call the provided number and wait for the validation code to be
entered.


{'fraction_non_alphanumeric': 0.12851619784028795, 'fraction_numerical': 0.009065457938941474, 'mean_word_length': 3.7541191381495564, 'pattern_counts': {'":': 0, '<': 16, '<?xml version=': 0, '>': 16, 'https://': 8, 'lorem ipsum': 0, 'www.': 12, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 10, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7121896', 'n_tokens_mistral': 2207, 'n_tokens_neox': 2047, 'n_words': 715}