Implementing Number Insight

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:

  • Establishing Identity (2FA)
  • Identifying outdated numbers
I want to determine the best way to reach my customer accurately.

Use Cases:

  • Identify if a customer is roaming (and would prefer to receive SMS instead of a call)
  • Identify if a customer is reachable to receive a call
  • Identify if a number is reachable via SMS
  • Identify if a number may be used for verification purposes
I want to reliably determine the network that a customer is connected to.

Use Case:

  • Reaching customers on a specific network (home or roaming)
I want to accurately identify where my customers are. Use Cases:
  • Send users a location specific communication
  • Identify potential fraud based on customer's location

I want to accurately identify who are my active customers with a specific handset.

Use Case:

  • Make marketing decisions based on subscriber status and make/model in use.
I want to accurately determine if customers are using a specific type of number.

Use Cases:

  • Identify if the number is virtual number (VoIP)
  • Identify if the number is a landline
  • Identify if the number is Premium or Special Services

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.

Was this article helpful?
0 out of 1 found this helpful
Have more questions? Submit a request