Phone Number Intelligence API - Carrier, Type and Risk

What is this number, who carries it, where is it, should you trust it, and is anyone there right now. Three services over one credential, one flat row per number.

What this actor does

• Identifies the line. Carrier, line type - mobile, landline, prepaid, VoIP, toll free, payphone and the rest - city, county, region, postal code, country, metro code, coordinates and time zone, with the time zone offsets included so a call list can be sorted by local hour rather than by guesswork.
• Scores fraud risk with an actual recommendation. A number comes back with a risk level, a score on a zero to one thousand scale, and a plain allow, flag or block, plus the reason codes behind it broken out by category. That is a decision you can route on rather than a number you have to interpret.
• Uses the lifecycle event to sharpen the score. The same number carries a very different risk when it is creating an account than when it is signing in to one it has held for two years. Telling the provider which moment this is makes the score meaningfully better, and it is one field.
• Separates blocklisting from risk. Some numbers are blocked by policy, meaning the account is not permitted to contact them at all. That is a different decision from a high score, it has different consequences, and it is kept as its own column with its own filter.
• Returns the number three ways. As you submitted it, cleansed for calling, and cleansed for messaging. Those are not always the same string, because a number that is valid to dial is not automatically valid to text, and the difference is exactly what a campaign needs to know before it sends.
• Checks SIM swaps, porting and forwarding. Twelve identity attributes are available on the lookup modes: the name and address on the line, whether a name you hold matches it, subscriber status, number deactivation, porting history and current porting status, recent SIM swap, active call status, appearance in known breaches, call forwarding, and age verification.
• Refuses ambiguous numbers instead of guessing. A number in national format resolves to a different subscriber in every country that shares the pattern, so a run that guesses returns confident answers about the wrong people. Inputs that cannot be a complete international number are refused before the request, cost nothing, and are recorded as refusals rather than silently dropped.
• Uses the authentication scheme that works everywhere. This provider offers two, and the simpler one is refused by the risk scoring route with a complaint about the header format rather than about the key, which reads as a broken credential when it is nothing of the sort. The signed scheme is the default here for that reason.
• Never charges for a miss. Only rows carrying a resolved number are billed.

Input

Field	What it does
mode	Risk scoring, plain lookup, or live reachability.
phones	Numbers to look up, one per line.
defaultCountryCode	Calling code to assume for national-format numbers.
addons	Identity attributes to request alongside the standard answer.
addonOptions	JSON settings for attributes that take their own parameters.
consentMethod	How consent to query the number was obtained.
consentTimestamp	When consent was obtained.
lifecycleEvent	What the end user is doing. Sharpens the risk score.
originatingIp	The end user's IP address. Sharpens the risk score.
recommendations	Keep only allow, flag or block rows.
riskLevels	Keep only these risk levels.
maxRiskScore	Keep only rows at or below this score.
phoneTypes	Keep only these line types.
countries	Keep only these countries.
excludeBlocklisted	Drop blocklisted numbers.
excludeProhibited	Drop numbers you may not contact at all.
requireReachable	Keep only numbers reachable right now.
authScheme	Signed, which works everywhere, or basic.
requestsPerMinute	Pace the run under your plan's rate limit.
skipNotFound	Leave misses and refusals out of the dataset.
maxResults	Hard cap on rows, and therefore on spend and run time.
clientId	Your own customer id. Stored as a secret.
apiKey	Your own API key. Stored as a secret.

Example output

{
  "found": true,
  "mode": "phone-intelligence",
  "query": "+14155552671",
  "referenceId": "0123456789ABCDEF0123456789ABCDEF",
  "phone": "14155552671",
  "phoneAsSubmitted": "+1 (415) 555-2671",
  "countryCallingCode": "1",
  "subscriberNumber": "4155552671",
  "callableNumber": "14155552671",
  "messageableNumber": "14155552671",
  "phoneTypeCode": 2,
  "phoneType": "MOBILE",
  "carrierName": "Verizon Wireless",
  "city": "San Francisco",
  "county": "San Francisco",
  "state": "CA",
  "postalCode": "94103",
  "countryName": "United States",
  "countryIso2": "US",
  "countryIso3": "USA",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timeZoneName": "America/Los_Angeles",
  "isBlocklisted": false,
  "blockCode": null,
  "isProhibited": false,
  "riskLevel": "low",
  "riskRecommendation": "allow",
  "riskScore": 120,
  "isLive": null,
  "statusCode": 300,
  "statusDescription": "Transaction successfully completed",
  "error": null,
  "raw": { }
}

Frequently asked questions

What is the difference between the three modes?

Risk scoring returns everything the plain lookup returns and adds a risk level, a score and a recommendation, along with the reason codes behind them. The plain lookup returns the carrier, line type, location and any identity attributes you enabled, without the risk verdict, and costs less of your provider credits when the verdict is not what you need. Live status answers one narrow question: is this number reachable on the network at this moment, which is a different thing from whether it is valid.

What does the risk score actually tell me?

It aggregates phone number intelligence, traffic patterns, machine learning and a shared industry data set into a single number from zero to one thousand, a level from low to high, and a recommendation of allow, flag or block. The recommendation is the part most systems should route on, because it is already calibrated; the raw score is what you tune against when the default thresholds do not fit your own tolerance.

Why does the lifecycle event matter?

Because risk is contextual. The same number is unremarkable when it signs in to an account it has held for two years and quite interesting when it creates a new account and immediately transacts. Telling the provider which moment this check belongs to lets its model weigh the signals accordingly. It costs nothing and it is one field, and leaving it out is the most common way to get a score that feels vague.

What is the difference between blocklisted and high risk?

A high risk score is an opinion about the number. Blocklisting is a decision that has already been made, sometimes because your account is not permitted to contact that number at all. Treating those as the same thing means either ignoring a contractual restriction or throwing away numbers that are merely uncertain, so they are two columns here, with two filters.

Why does the actor return the number three times?

Because the provider does, and the differences matter. There is the number as you submitted it, the number cleansed into a form that can be dialled, and the number cleansed into a form that can be texted. Those are not always the same string, and a campaign that assumes they are will send to a number that cannot receive messages. Each comes with its own cleanse code saying what had to be changed.

What are the identity attributes and do I need to do anything to use them?

They are twelve separate products layered on the lookup: the name and address on the line, a match check against a name and address you already hold, subscriber status, number deactivation, porting history and live porting status, recent SIM swap, active call status, breach appearance, call forwarding and age verification. Most must be enabled on your account by the provider before they return anything, and several require you to record how you obtained the subscriber's consent to query the number. The consent record is only sent when you actually supply one, because an invented consent record is worse than none.

Why does the actor refuse some of my numbers before sending them?

Because a number written in national format is genuinely ambiguous. The provider addresses numbers in complete international form, and the same digits belong to different subscribers in every country sharing that pattern, so guessing produces confident answers about the wrong people. A number written with a plus or a leading double zero already carries its country code and is taken as given. A number starting with a trunk zero is national format, so without a default calling code there is nothing to resolve it against and it is refused. Anything else is read as already complete, but held to a ten digit minimum, because a seven digit string with no marker is a local number someone forgot to qualify. Refusals cost nothing and are written to the dataset as refusals, so a run that ignored a fifth of its input does not look like a run whose provider found nothing. Set a default calling code if your list is genuinely all from one country.

Which authentication scheme should I use?

Signed, which is the default. It builds a request signature from your API key and is accepted by every route. The basic scheme is accepted by the two lookup routes and refused outright by the risk scoring route, which complains that the authorization header is not in the correct format rather than that the key is wrong, and that error sends people hunting for a credential problem that does not exist. The option to switch is there, and the actor warns you if you pick basic for a scoring run.

Do I need my own API key?

Yes. This actor does not include data access. You use your own customer id and API key from Telesign, which is the provider whose phone intelligence API this actor calls, from their portal. These are two separate values and both are required: the customer id goes in clientId and the API key in apiKey, both stored as Apify secrets. Your own plan, credit balance and terms apply, and the identity attributes above are enabled per account rather than by default.

What happens when a number returns nothing?

An invalid or unreachable number is a verdict, not a miss: the provider telling you the line does not exist is the question you asked, so that row is written and billed like any other. A miss is a number the provider returned no record for at all, and a refusal is an input that never left this actor. Both are written with found: false and never billed. Set skipNotFound to true to leave them out of the dataset entirely.

How much does a run cost?

Pricing is pay per result: you are charged for each number resolved into the dataset, and never for misses, for locally refused inputs, for rows dropped by the filters, or for duplicates. Apify platform usage is included in the per-result price. Your own API provider's credit balance is separate and billed by them, and note that the identity attributes are charged individually by the provider on top of the base lookup.

Keyword map

phone number intelligence API, phone number lookup API, carrier lookup, line type detection, mobile or landline check, HLR lookup, phone validation API, phone fraud detection, phone risk score, SMS fraud prevention, SIM swap detection, number porting check, call forwarding detection, number deactivation check, subscriber status, caller name lookup, reverse phone lookup, phone to address, phone geolocation, time zone by phone number, account takeover prevention, bot signup prevention, two factor authentication risk, KYC phone verification, phone reputation API, live phone status