Twilio Incoming Phone Numbers Releasing/Deletion

Getting my feet wet with Twilio, I've discovered a fun little caveat in the acquisition/purchasing and releasing process of an incoming phone number.

Using their API for my SMS/Emailing application, my application requires the purchasing of a Twilio phone number. I then store this phone number locally in a column under a lists record.

When the user the deletes a list record, I wanted to release this number from Twilio. Twilio numbers cost $1/month, so if it's not going to be used, it needs to be released.

Through various sources, I was under the impression that a phone number could be deleted like so:

$client = new Services_Twilio('sid', 'token');
$number = $client->account->incoming_phone_numbers->get('phone number');
$client->account->incoming_phone_numbers->delete('phone number');

For example, this GitHub issue states that an incoming phone number should be retrieved using the phone number itself (which I have stored in my table), and then deleted through the delete method through the $number->id (or rather, the $number->sid) property.

The issue is this:
The response to the get method on the incoming_phone_numbers object is a Services_Twilio_Rest_IncomingPhoneNumber object type/instance. When the property passed in to retrieve this object is the phone number, the $number->sid value is the telephone number itself.

The deletion will fail when this is the case. The delete method expects the $number->sid property to be formatted something like:

PN661ee8899367de91f9fbcf7bec9ff878

The only time this can be properly retrieved is using the following example, provided by Twilio:

$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';

$client = new Services_Twilio($accountSid, $authToken);
$number = $client->account->incoming_phone_numbers;
foreach($numbers as $number) {

    // Delete just the first number, then quit.
    $client->account->incoming_phone_numbers->delete($number->sid);
    break;
}

The error I was getting when trying to delete a Services_Twilio_Rest_IncomingPhoneNumber instance was the following:

..exception 'Services_Twilio_RestException' with message 'The requested
resource was not found' in..

Resolution

When purchasing a telephone number from Twilio, I should store not just the Twilio number (passed under the phone_number property), but also the sid property.

Then, when I want to release a number, I do so using exclusively that sid property.

I'm not sure if this was an oversight on Twilio's side, if their documentation hasn't been updated after an API change, or if I'm simply doing something wrong (most probable case), but I hope this helps anyone else who is having trouble releasing a Twilio phone number, using the phone number itself as a getter.

Samples

When calling the get method using the phone number as the parameter, here is the sid property that is returned:

            [principal:protected] => Array
                (
                    [sid] => +17158432908
                    [params] => Array
                        (
                        )

                )

            [cache:protected] => 
        )

    [subresources:protected] => Array
        (
        )

)

When calling the get method using the sid provided during the purchasing stage, here is the respective response:

            [principal:protected] => Array
                (
                    [sid] => PN661ee8899367de91f9fbcf7bec9ff878
                    [params] => Array
                        (
                        )

                )

            [cache:protected] => 
        )

    [subresources:protected] => Array
        (
        )

)

Hope that helps.

Possible Workaround

In looking more into the Twilio API, I realize it may be possible to get around this issue while storing on the phone number.

I would imagine there is an API call whereby when only the phone number is given, the response is similar to that of:

$number = $client->account->incoming_phone_numbers;

I'll look into it, and update this post accordingly.