You can use the Plivo Lookup API to avoid sending messages to invalid or inaccessible numbers, which can help you save money on your campaign.

The Lookup API determines whether a number is a real phone number and belongs to an operator. If a number is invalid or the lookup fails, our server returns an error code and a message that explains the problem.

For example, consider a lookup request for the phone number 1-202-555-1234:

A successful Lookup API response returns an HTTP status code of 200.

An unsuccessful response returns an api_id, an error code, and an error message.

    "api_id": "",
    "error_code": 404,
    "message": "Phone number is invalid or does not exist."

This table shows the potential error codes and descriptions that an unsuccessful lookup request might return.

Plivo Lookup Error Codes

HTTP Status Codes Plivo Error Codes Reason Description
401 401 Auth ID and/or Auth Token is invalid. You receive this response when you use invalid credentials to access the API.
402 402 Account does not have sufficient balance to fulfill the request. Prepaid account has insufficient balance. This error is not applicable for postpaid customers. Please recharge your account.
403 403 Account is forbidden from accessing resource. Customer has not been subscribed to the Lookup Service. Please contact Plivo support.
404 404 Phone number is invalid or does not exist. Phone number is either invalid or doesn’t exist.
400 160 Request type not specified or is invalid. Lookup API requires the query parameter type to be set in the request. This error occurs when this parameter is missing or if the value passed with the parameter is invalid.

Check the Number Lookup API documentation to learn about the API parameters.
500 300 Failed to process request due to internal server failure. Plivo is unable to process the API request due to internal issues.

Contact Plivo support.
5XX NA   Contact Plivo support.