Issue

When using the Twilio Calls API to place outbound calls, the API request may return a successful response (HTTP 201 Created) even if the destination number is invalid or unreachable. Customers often need a reliable way to confirm whether a call actually went through or failed, especially to detect failures caused by invalid or unreachable phone numbers.

Symptoms

• The API request to create a call returns success, but the call does not reach the intended recipient.
• The destination number may be inactive, unreachable, or not assigned, but no error is returned at the API request stage.
• Customers need to programmatically confirm the final outcome of each call.

Product

Programmable Voice

Environment

Twilio Console

Cause

The Twilio Calls API validates the request parameters and initiates the call process, but it does not verify the real-time reachability of the destination number at the time of the API request. Many numbers may be structurally valid (correct format and assigned to a carrier) but not reachable due to being inactive, disconnected, or blocked.

Resolution

To reliably determine the outcome of each outbound call and detect unreachable or invalid numbers, use a combination of the following Twilio features:

1. Lookup API (Pre-call Validation)

• The Twilio Lookup API checks if a phone number is structurally valid and assigned according to international numbering plans.
• Limitation: The Lookup API’s "valid": true result only means the number is correctly formatted and assigned, not that it is currently reachable or active.
• For advanced reachability checks, the Line Status package (currently in private beta) can provide information such as Active, Reachable, Unreachable, Inactive, or Unknown.

2. StatusCallback Webhook (Real-Time Call Status)

• When creating a call, specify a StatusCallback URL in your API request.
• Twilio will send HTTP requests (webhooks) to this URL to notify you of call status changes, such as completed, failed, busy, or no-answer.
• The webhook payload includes CallStatus and ErrorCode parameters, which help identify the final outcome and reason for failure (if any).

3. Call Resource Status via API (Post-call Reconciliation)

• After the call is initiated, you can query the Call resource using the Call SID.
• The status and error_code fields indicate the final state of the call and the reason for failure, if applicable.

Example Workflow

1. Validate the number before calling:
   Use the Lookup API to check if the number is valid for the region.
2. Initiate the call with StatusCallback:
   Include a StatusCallback URL in your API request to receive real-time updates.
3. Monitor call outcome:
   In your webhook handler, check for failed, no-answer, or other non-completed statuses and review the ErrorCode.
4. (Optional) Query call status via API:
   For reconciliation or reporting, fetch the Call resource and review the final status and error code.

Additional Information 

To confirm the outcome of outbound calls and detect unreachable numbers, combine pre-call validation (Lookup API), real-time monitoring (StatusCallback), and post-call reconciliation (Call resource queries). For advanced reachability, consider the Line Status package.

• The Lookup API does not guarantee reachability only format and assignment.
• The Line Status package provides enhanced reachability data but is in private beta.
• StatusCallback and Call resource queries are the most reliable way to confirm the actual outcome of a call.

Below you will find references to useful documents:

• Twilio Lookup API Documentation
• Line Status Package (Beta)
• Tracking the Status of an Outbound Twilio Voice Call
• Call Resource API Reference

If you need further assistance or code samples, please reach out to Twilio Support.