Today we’re happy to announce the release of a small and useful feature: status callbacks for caller ID verification calls. This allows your application be notified when a verification call succeeds or fails so you can notify your users without having to poll the REST API.
To use this new feature, make a POST request to the OutgoingCallerIds list resource and optionally include a StatusCallback parameter to indicate where you would like to be notified when the call ends. You can also choose the HTTP method to use with the StatusCallbackMethod parameter. For example:
POST /2010-04-01/Accounts/AC12345/OutgoingCallerIds PhoneNumber=+14155551212 FriendlyName=Jenny's Cell StatusCallback=http://example.com/callback
The verification call will be placed as usual. When the call completes and the number called has successfully entered the verification code, your callback URL will be requested with the following information (along with the rest of the standard parameters):
POST http://example.com/callback To=+14155551212 CallStatus=completed VerificationStatus=success OutgoingCallerIdSid=PN12345
The OutgoingCallerIdSid represents the newly-created OutgoingCallerId resource for the verified number. If the call ends without the code being entered correctly, the URL will be requested with the following:
POST http://example.com/callback To=+14155551212 CallStatus=completed VerificationStatus=failed
This callback will also notify you if a call is not answered or the line was busy. Complete documentation is available in the REST API docs for OutgoingCallerIds.