Add phone number property update example

Kevin Burke · Kevin Burke · commit 8cceda583316 · 2012-07-13T20:00:46.000-07:00
Also move caller id validation to its own page
diff --git a/docs/usage/caller-ids.rst b/docs/usage/caller-ids.rst
@@ -0,0 +1,21 @@
+
+Validate a Phone Number
+-----------------------
+
+Validating a phone number 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 = "YYYYYYYYYYYYYYYYYY"
+
+    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
+    response = client.caller_ids.validate("+44 9876543212")
+    print response["validation_code"]
+
+Twilio will call the provided number and wait for the validation code to be
+entered.
+
diff --git a/docs/usage/phone-numbers.rst b/docs/usage/phone-numbers.rst
@@ -61,7 +61,6 @@ 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
 ---------------
 
@@ -78,45 +77,53 @@ If you've found a phone number you want, you can purchase the number.
     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).
-
+However, it's easier to purchase numbers after finding them using search (as
+shown in the first example).
 
-Changing Applications
-----------------------
+Updating Properties on a Number
+------------------
 
-An :class:`Application` encapsulates all necessary URLs for use with phone numbers. Update an application on a phone number using :meth:`update`.
+To update the properties on a phone number, call :meth:`update`
+on the phone number object, with any of the parameters
+listed in the `IncomingPhoneNumbers Resource documentation
+<http://www.twilio.com/docs/api/rest/incoming-phone-numbers>`_
 
 .. 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 = "YYYYYYYYYYYYYYYYYY"
 
     client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
-    number = client.phone_numbers.update(phone_sid, sms_application_sid="AP123")
+    for number in client.phone_numbers.list(api_version="2010-04-01"):
+        number.update(voice_url="http://twimlets.com/holdmusic?" + 
+            "Bucket=com.twilio.music.ambient", 
+            status_callback="http://example.com/callback")
 
-See :doc:`/usage/applications` for instructions on updating and maintaining Applications.
+Changing Applications
+----------------------
 
-Validate a Phone Number
------------------------
-Validating a phone number is quick and easy.
+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 = "YYYYYYYYYYYYYYYYYY"
 
     client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
-    response = client.caller_ids.validate("+9876543212")
-    print response["validation_code"]
+    number = client.phone_numbers.update(phone_sid, sms_application_sid="AP123")
+
+See :doc:`/usage/applications` for instructions on updating and maintaining Applications.
+
+Validate a Phone Number
+-----------------------
 
-Twilio will call the provided number and wait for the validation code to be
-entered.
+See validation instructions here: :doc:`/usage/caller-ids`:
 
