How long will it take for me to get a NI query response?
The API has a maximum response time of 15 seconds. The average response time should be of the order of a few seconds, so if you consistently see higher latencies, submit a Support request. The API latency depends upon latencies of several systems that we work with to determine results for a number and will therefore vary.
How should I parse the API callbacks?
You may decide to either receive each individual callback as they become available or to wait for the final callback with the most complete information. Should you decide to receive all callbacks, your requests should include the parameter 'include-intermediate-callbacks=true’. In this case, the final callback will be identified by the parameter ‘final=true’. This parameter is optional and if unspecified you shall only receive the final callback with the most complete information we could determine about the number. Unless your application is very time sensitive (response time < 500 ms) we do not recommend using intermediate callbacks.
How should I acknowledge the response?
You must ACK each callback with a 200 OK response. Number Insight API has a retry mechanism for a maximum of 24 hours (1 day) with exponential back-off. Number Insight Callbacks will be retried periodically for 24 hours in the event of not receiving the corresponding HTTP 200 response from your server. After this time-frame the Callback will be dropped and no longer available.
What can I use Number Insights for?
As long as your application is respecting the applicable Data Protection Laws, you can use the information for decision making. Roaming (country, network) and Reachability data is disallowed by law from being persisted within your application's databases in several geographies. Some of the popular uses of NI API (our application) are:
| Description | Comments |
| I want to determine if a number is valid reliably, as quickly as possible and at the minimum cost. |
Use Cases:
|
| I want to determine the best way to reach my customer accurately. |
Use Cases:
|
| I want to reliably determine the network that a customer is connected to. |
Use Case:
|
| I want to accurately identify where my customers are. | Use Cases:
|
|
I want to accurately identify who are my active customers with a specific handset. |
Use Case:
|
| I want to accurately determine if customers are using a specific type of number. |
Use Cases:
|
I got one field as unknown; are the other fields correct?
Yes, one unknown attribute does not impact the verity of the others.
I have an error code in my callback but some fields are populated; can I trust the populated fields?
Yes. Note that there are two kinds of errors you can get. Temporary (potentially recoverable) errors; identified by error code '1': Implies that one of the information systems timed out, so a later request may be able to produce more information. In others, this may be a permanent error - such as no information available for the number from any system that we looked at. You should refer to the error code tables in the troubleshooting section for more information on this.
Articles in this section
- What are the levels of Number Insight APIs?
- Number Insight Callback Response Status Code Definitions
- Number Type Incorrect in Number Insight
- What is the Validity Period for a Number Insight?
- What do I need to get started with using Number Insight?
- How many requests can I make to Number Insight?
- How are Number Insight requests billed?
- What numbers can I get Number Insight for?
- What number format is acceptable for the Number Insight API?
- Will the owner of the phone number be notified of my using Number Insight?