Twilio
Download:
twilio-documentation.zip

OutgoingCallerIds Resource

An resource represents an outgoing Caller ID that you have registered with Twilio for use when making an outgoing call or using the verb.

Resource URI

/2008-08-01/Accounts/{YourAccountSid}/OutgoingCallerIds

Resource Properties

OutgoingCallerID Resource Properties
Property Description
Sid A 34 character string that uniquely identifies this resource.
DateCreated The date that this resource was created, given in RFC 2822 format.
DateUpdated The date that this resource was last updated, given in RFC 2822 format.
FriendlyName A human readable descriptive text for this resource, up to 64 characters long. By default, the FriendlyName is a nicely formatted version of the PhoneNumber.
AccountSid The id of the account with which this resource is associated.
PhoneNumber The 10 digit incoming phone number. Always presented as a 10 digit number, with no "decoration" (like dashes, parentheses, etc.)

OutgiongCallerIds List Resource

Resource URI

/2008-08-01/Accounts/{YourAccountSid}/OutgoingCallerIds

HTTP Methods

GET

Returns a list of <OutgoingCallerId> elements, each representing a Caller ID number validated for your account, under an <OutgoingCallerIds> list element, which includes paging information.

Example:

<TwilioResponse>  
    <OutgoingCallerIds page="0" numpages="1" pagesize="50" total="2" start="0" end="0">  
        <OutgoingCallerId>  
            <Sid>PNe536dfda7c6184afab78d980cb8cdf43</Sid>  
            <AccountSid>AC35542fc30a091bed0c1ed511e1d9935d</AccountSid>  
            <FriendlyName>Bob Cell Phone</FriendlyName>  
            <PhoneNumber>4158675309</PhoneNumber>  
            <DateCreated>Tue, 01 Apr 2008 11:26:32 -0700</DateCreated>  
            <DateUpdated>Tue, 01 Apr 2008 11:26:32 -0700</DateUpdated>  
        </OutgoingCallerId>  
        <OutgoingCallerId>  
            <Sid>PNe536dfda7c6DDd455fed980cb83345FF</Sid>  
            <AccountSid>AC35542fc30a091bed0c1ed511e1d9935d</AccountSid>  
            <FriendlyName>Company Main Line</FriendlyName>  
            <PhoneNumber>4158675310</PhoneNumber>  
            <DateCreated>Tue, 01 Apr 2008 11:26:32 -0700</DateCreated>  
            <DateUpdated>Tue, 01 Apr 2008 11:26:32 -0700</DateUpdated>  
        </OutgoingCallerId>  
    </OutgoingCallerIds>   
</TwilioResponse>

POST

Adds a new CallerID to your account. After making this API call, Twilio will return to you a validation code and Twilio will dial the phone number given to perform validation. The code returned must be entered via the phone before the CallerID will be added to your account. Parameters must include:

OutgoingCallerId POST Parameters
Param Optional Description
PhoneNumber Required The 10 digit phone number, but you can specify it in any readable format, such as 415-555-1212 or (415) 555.1212 or 1-415-555-1212
FriendlyName Optional A human readable description of Caller ID resource, with maximum length 64 characters. Ex.: 'My Cell Phone'. Defaults to a nicely formatted version of the PhoneNumber.
CallDelay Optional The number of seconds, between 0 and 60, to delay before initiating the Validation Call. Defaults to 0.

This will create a new CallerID validation request, which initiates a call to the phone number provided requesting that they enter the validation code. The validation request is represented in the response in a resource with the following properties:

OutgoingCallerID POST Response Properties
Property Description
AccountSid The account to which the Validation Request belongs.
PhoneNumber The 10 digit phone number that is being validated.
FriendlyName The friendly name you provided, if any.
ValidationCode The 6 digit validation code that must be entered via the phone to validate this phone number for Caller ID.

For example:

POST /2008-08-01/Accounts/AC309475e5fede1b49e100272a8640f438/OutgoingCallerIds HTTP/1.1 \ FriendlyName=My+Home+Phone+Number&PhoneNumber=4158675309

<TwilioResponse>  
    <ValidationRequest> 
        <AccountSid>AC309475e5fede1b49e100272a8640f438</AccountSid>
        <PhoneNumber>4158675309</PhoneNumber> 
        <ValidationCode>123456</ValidationCode>
    </ValidationRequest> 
</TwilioResponse>

Typically, you would present that validation code to the user who is trying to validate their phone number. If you Add a Caller ID via the Twilio website, this is what we're doing.

PUT

Not Supported.

DELETE

Not Supported.

URL Filtering

You may limit the list by providing certain query string parameters to the listing resource. Note, parameters are case-sensitive:

  • PhoneNumber: Only show the caller id resource that exactly matches this ten digit phone number.
  • FriendlyName: Only show the caller id resources that exactly matches this name. For example:

https://api.twilio.com/2008-08-01/Accounts/AC309475e5fede1b49e100272a8640f438/OutgoingCallerIds?PhoneNumber=4158675309

Would only show the caller id record for phone number (415) 867-5309.

OutgoingCallerIds Instance Resource

Resource URI

/2008-08-01/Accounts/{YourAccountSid}/OutgoingCallerIds/{OutgoingCallerIdSid}

This resource represents an individual caller id registered to your account.

HTTP Methods

GET

GET /2008-08-01/Accounts/AC309475e5fede1b49e100272a8640f438/OutgoingCallerIds/PNe536dfda7c6184afab78d980cb8cdf43 HTTP/1.1

<TwilioResponse> 
    <OutgoingCallerId> 
        <Sid>PNe536dfda7c6184afab78d980cb8cdf43</Sid> 
        <AccountSid>AC35542fc30a091bed0c1ed511e1d9935d</AccountSid> 
        <FriendlyName>My Home Phone Number</FriendlyName> 
        <PhoneNumber>4158675309</PhoneNumber> 
        <DateCreated>Tue, 01 Apr 2008 11:26:32 -0700</DateCreated> 
        <DateUpdated>Tue, 01 Apr 2008 11:26:32 -0700</DateUpdated> 
    </OutgoingCallerId> 
</TwilioResponse>

PUT or POST

Update the caller id, and return the updated resource. There is only one field that you may update:

OutgoingCallerId POST Parameters
Param Optional Description
FriendlyName Required A human readable description of Caller ID resource, with maximum length 64 characters. Ex.: 'My Cell Phone'. Defaults to a nicely formatted version of the PhoneNumber.

DELETE

Delete the caller id from your account. An HTTP 204 response is returned, with no body.