Mark Holloway2024-01-08T14:08:34+00:00https://www.markholloway.comUsing Twilio Lookup API for phone number validation and fraud prevention2019-03-16T00:00:00+00:00https://www.markholloway.com/2019/03/16/twilio-lookup-api<p>With the Twilio <code class="language-plaintext highlighter-rouge">Lookup</code> API it’s possible to instantly obtain information about a caller such as caller name, carrier name, carrier type, number type, and porting history.
<!--more--></p>
<p>Twilio provides the <code class="language-plaintext highlighter-rouge">Lookup</code> API as a way to validate if a number is real or ficticious and provide additional details associated with the number. The data Twilio provides is real-time. This is critical to knowing if a phone number was stolen and ported or sim-swapped. People who intend to commit fraud operate quickly and having real time data available is critical to fraud prevention.</p>
<h2 id="use-cases-for-lookup">Use cases for Lookup</h2>
<p>When users visit a web site and fill out a form they may be required to enter their mobile or home phone number. Lookup can instantly validate the formatting and make sure digits were not inadvertantly mistyped. If a user enters a landline in a mobile number field, which may also have an opt-in for SMS, Lookup will recognize the number entered is not a mobile number.</p>
<p>In other cases malicious users may obtain numbers in bulk with the intention of using them for fraud. Lookup can differentiate easily obtained <code class="language-plaintext highlighter-rouge">VoIP</code> numbers from landline and mobile numbers.</p>
<p>Often times Contact Centers would like to know if callers are calling from a mobile phone and will use Lookup to note the information and make the Agent aware the user is calling from a mobile phone and present the “In case we get dropped…” script.</p>
<p>True story. A top C level of a crypto-currency company had his phone number stolen, ported to another carrier, and sim-swapped within minutes. A person with malicious intent began accessing financial accounts to start transferring money. 2FA with authorization codes sent via SMS to the mobile number were not an issue since the number was now controlled by someone else. This all went down within 45 minutes. There are many ways this could have been prevented, but one simple step is when a user’s mobile number has been very recently ported, whether minutes, hours, or days, do not allow financial transaction beyond a trivial amount.</p>
<h2 id="using-lookup">Using Lookup</h2>
<p>To immediately see Lookup in action for Disney World’s number <code class="language-plaintext highlighter-rouge">4079395277</code> log in to the Twilio console and on the left side of the screen select Lookup. If you do not see Lookup click on the three <code class="language-plaintext highlighter-rouge">...</code> on the bottom left bar. Using Lookup in console is handy for demonstration purposes or manually performing a lookup request.</p>
<p><img src="/blog/assets/2019-03-16/lookup-console.png" alt="" /></p>
<p>Here is an example of Lookup using <code class="language-plaintext highlighter-rouge">CURL</code> for the same phone number. The results are returned by Twilio in JSON format. I use the <code class="language-plaintext highlighter-rouge">-o</code> option to save the results in a file called <code class="language-plaintext highlighter-rouge">lookup.json</code></p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
curl -XGET "https://lookups.twilio.com/v1/PhoneNumbers/4079395277?CountryCode=US&Type=carrier" \
-u '{SID}:{AuthToken}' \
-o lookup.json
</code></pre></div></div>
<h2 id="nodejs-example">Node.js example</h2>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
<span class="kd">const</span> <span class="nx">accountSid</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">{SID}</span><span class="dl">'</span><span class="p">;</span>
<span class="kd">const</span> <span class="nx">authToken</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">{AuthToken}</span><span class="dl">'</span><span class="p">;</span>
<span class="kd">const</span> <span class="nx">client</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="dl">'</span><span class="s1">twilio</span><span class="dl">'</span><span class="p">)(</span><span class="nx">accountSid</span><span class="p">,</span> <span class="nx">authToken</span><span class="p">);</span>
<span class="nx">client</span><span class="p">.</span><span class="nx">lookups</span><span class="p">.</span><span class="nx">phoneNumbers</span><span class="p">(</span><span class="dl">'</span><span class="s1">+14079395277</span><span class="dl">'</span><span class="p">)</span>
<span class="p">.</span><span class="nx">fetch</span><span class="p">({</span><span class="na">type</span><span class="p">:</span> <span class="dl">'</span><span class="s1">caller-name</span><span class="dl">'</span><span class="p">})</span>
<span class="p">.</span><span class="nx">then</span><span class="p">(</span><span class="nx">phone_number</span> <span class="o">=></span> <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">phone_number</span><span class="p">.</span><span class="nx">callerName</span><span class="p">));</span>
</code></pre></div></div>
<h2 id="python-example">Python example</h2>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
<span class="kn">from</span> <span class="nn">twilio.rest</span> <span class="kn">import</span> <span class="n">Client</span>
<span class="n">account_sid</span> <span class="o">=</span> <span class="s">'{SID}'</span>
<span class="n">auth_token</span> <span class="o">=</span> <span class="s">'{AuthToken}'</span>
<span class="n">client</span> <span class="o">=</span> <span class="n">Client</span><span class="p">(</span><span class="n">account_sid</span><span class="p">,</span> <span class="n">auth_token</span><span class="p">)</span>
<span class="n">phone_number</span> <span class="o">=</span> <span class="n">client</span><span class="p">.</span><span class="n">lookups</span><span class="p">.</span><span class="n">phone_numbers</span><span class="p">(</span><span class="s">'+14079395277'</span><span class="p">).</span><span class="n">fetch</span><span class="p">(</span>
<span class="nb">type</span><span class="o">=</span><span class="s">'caller-name'</span>
<span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">phone_number</span><span class="p">.</span><span class="n">callerName</span><span class="p">)</span>
</code></pre></div></div>
<p>Results returned in <code class="language-plaintext highlighter-rouge">JSON</code> format</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nl">"caller_name"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nl">"caller_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"DISNEY RESV CTR"</span><span class="p">,</span><span class="w">
</span><span class="nl">"caller_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"BUSINESS"</span><span class="p">,</span><span class="w">
</span><span class="nl">"error_code"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="nl">"country_code"</span><span class="p">:</span><span class="w"> </span><span class="s2">"US"</span><span class="p">,</span><span class="w">
</span><span class="nl">"phone_number"</span><span class="p">:</span><span class="w"> </span><span class="s2">"+14079395277"</span><span class="p">,</span><span class="w">
</span><span class="nl">"national_format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"(407) 939-5277"</span><span class="p">,</span><span class="w">
</span><span class="nl">"carrier"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nl">"mobile_country_code"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w">
</span><span class="nl">"mobile_network_code"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w">
</span><span class="nl">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Smart City Telecommunications, LLC dba Smart City Telecom"</span><span class="p">,</span><span class="w">
</span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"landline"</span><span class="p">,</span><span class="w">
</span><span class="nl">"error_code"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="nl">"add_ons"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w">
</span><span class="nl">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://lookups.twilio.com/v1/PhoneNumbers/+14079395277?Type=carrier&Type=caller-name"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>