- API & Docs
An OutgoingCallerId instance resource represents a single verified number that
may be used as a caller ID when making outgoing calls via the REST
API and within the TwiML
<Dial> verb. The
OutgoingCallerIds list resource represents the set of an account's verified
|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
|AccountSid||The unique id of the Account responsible for this Caller Id.|
|PhoneNumber||The incoming phone number. Formatted with a '+' and country code e.g., +16175551212 (E.164 format).|
|Uri||The URI for this resource, relative to
Updates the caller id, and returns the updated resource if successful.
There is only one field that you may update:
|FriendlyName||A human readable description of a Caller ID, with maximum length of 64 characters. Defaults to a nicely formatted version of the phone number.|
The response format is identical to the HTTP GET response documented above.
Deletes the caller ID from the account. Returns an HTTP 204 response if successful, with no body.
Returns a list of OutgoingCallerId resource representations, each representing a Caller ID number valid for an account. The list includes paging information.
The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:
|PhoneNumber||Only show the caller id resource that exactly matches this phone number.|
|FriendlyName||Only show the caller id resource that exactly matches this name.|
Just grab the entire list of an account's caller IDs.
Only show the caller id record for phone number (415) 867-5309.
Adds a new CallerID to your account. After making this request, 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. The following parameters are accepted:
|PhoneNumber||The phone number to verify. Should be formatted with a '+' and country code e.g., +16175551212 (E.164 format). Twilio will also accept unformatted US numbers e.g., (415) 555-1212, 415-555-1212.|
|FriendlyName||A human readable description for the new caller ID with maximum length 64 characters. Defaults to a nicely formatted version of the number.|
|CallDelay||The number of seconds, between 0 and 60, to delay before initiating the verification call. Defaults to 0.|
|Extension||Digits to dial after connecting the verification call.|
|StatusCallback||A URL that Twilio will request when the verification call ends to notify your app if the verification process was successful or not. See StatusCallback parameter below.|
|StatusCallbackMethod||The HTTP method Twilio should use when requesting the above URL. Defaults to POST.|
This will create a new CallerID validation request within Twilio, which initiates a call to the phone number provided and listens for a validation code. The validation request is represented in the response by the following properties:
|AccountSid||The unique id of the Account to which the Validation Request belongs.|
|PhoneNumber||The incoming phone number being validated, formatted with a '+' and country code e.g., +16175551212 (E.164 format).|
|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.|
|CallSid||The unique id of the Call created for this validation attempt.|
After the verification call ends, Twilio will make an asynchronous HTTP request to the StatusCallback URL if you provided one in your API request. By capturing this request, you can determine when the call ended and whether or not the number called was successfully verified.
Twilio passes the same parameters to your application in its asynchronous request to the StatusCallback URL as it does in a normal status callback request. The full list of parameters and descriptions of each are in the TwiML Voice: Twilio's Request documentation.
The verification status callback request also passes these additional parameters:
|VerificationStatus||Describes whether or not the person called correctly entered the validation code. Possible values are
|OutgoingCallerIdSid||If the verification process was successful, the SID value of the newly-created OutgoingCallerId resource for the verified number.|
Here is a typical request and response. Typically, you would present the validation code from the response to the user who is trying to verify his or her phone number. If you verify a number via the Twilio website, this is exactly what we're doing.