Reverse Phone Lookup API - Caller ID, Owner and Address Data

Find out who is behind a phone number, whether that number is still in service, and whether the lead who typed it into your form is who they said they were. One flat row per lead, per phone owner and per resident of an address.

What this actor does

• Names the owner behind a number. Caller identification returns the person or business a number belongs to, with first, middle and last name, alternate names, age range, gender, whether the owner is a person or a business, the industry for businesses, and how long that number has been linked to them.
• Returns every owner, not just the first. Reverse phone writes one row per owner on record. This is the difference between catching a reassigned mobile and calling the last person who held the number: when a number has two owners, both are written, and which one is current is a question you can answer from the link dates rather than one the actor decides for you.
• Tells a live number from a dead one. Phone validation returns line type, carrier, prepaid flag, country and an activity score from 0 to 100. The activity score is the field that matters on an aging list: a number can be perfectly well formed, correctly carriered, and disconnected eight months ago.
• Grades a whole lead at once. Lead grading takes the name, phone, email, postal address and signup IP from one form submission and grades the phone, the email and the address A to F, each with its own name match, plus an IP trust score and how far that IP sits from the address given. The lists are read row by row rather than crossed, so row one of each list is one lead.
• Screens for litigators before you dial. The litigator add-on flags numbers belonging to known TCPA litigators, and excludeLitigatorRisk drops them from the dataset outright.
• Resolves an address to the people at it. Reverse address returns the current residents of a postal address, each with name, age range, gender, historical addresses and associated people. Address validation answers the narrower question of whether an address is real, active, commercial and deliverable, with latitude and longitude.
• Filters on the fields that decide a call list. Keep only A and B graded phones, keep only mobiles, drop non-fixed VOIP, require a minimum activity score, require the name to match the number, or require the phone to be valid at all.
• Handles rate limits and quotas differently. A per-second rate limit is retried with backoff because it clears by itself. A used-up monthly quota is recognised from the provider's own message and stops the run with what it has, rather than burning retries on something waiting will not fix.
• Never charges for a miss. Only rows carrying a resolved result are billed.

Input

Field	What it does
mode	Lead grading, phone validation, caller identification, caller name, reverse phone, reverse address or address validation.
phones	Phone numbers to look up, and the phone half of each lead.
names	The name each lead gave you. Read row by row against the other lists.
emails	The email each lead gave you, in the same order as the names.
addresses	Addresses to look up, or the address half of each lead.
ipAddresses	The IP each lead submitted from, in the same order as the names.
businessNames	The business name on the lead, when the lead is a company.
countryCode	Country for the postal addresses, for example US.
countryHint	Country used to read phone numbers written in local format.
nameHint, postalCodeHint	Rank the owners returned for a number.
addOns	Litigator screening, spam screening, email deliverability, email age.
keepContactGrades	Keep only these phone grades, A to F.
keepLineTypes	Keep only these line types, such as mobile only.
minActivityScore	Drop numbers below this activity score.
requireValidPhone, requireNameMatch, excludeLitigatorRisk	Quality gates.
skipNotFound	Leave unresolved inputs out of the dataset.
requestsPerMinute	Pace the run under your plan's rate limit.
maxResults	Hard cap on rows, and therefore on spend and run time.
apiKey	Your own API key. Stored as a secret.

Example output

{
  "found": true,
  "mode": "reversePhone",
  "query": "+12065550100",
  "phoneId": "Phone.f8a7c1d2",
  "phoneNumber": "+12065550100",
  "phoneIsValid": true,
  "phoneLineType": "Mobile",
  "carrier": "T-Mobile USA",
  "isPrepaid": false,
  "isCommercial": false,
  "countryCallingCode": "1",
  "personId": "Person.4b19e0aa",
  "name": "Jane A Doe",
  "firstName": "Jane",
  "middleName": "A",
  "lastName": "Doe",
  "alternateNames": ["Jane Doe"],
  "ageRange": "35-39",
  "gender": "Female",
  "ownerType": "Person",
  "industry": null,
  "linkToPhoneStartDate": "2019-04-01",
  "address": "100 Main St, Seattle, WA 98104",
  "city": "Seattle",
  "stateCode": "WA",
  "postalCode": "98104",
  "latitude": 47.6034,
  "longitude": -122.3295,
  "warnings": null,
  "partialError": null,
  "error": null
}

Lead grading rows carry phoneGrade, emailGrade, phoneActivityScore, phoneNameMatch, emailNameMatch, addressIsValid, ipTrustScore and ipDistanceToAddressMiles instead. Every row also carries raw, the provider's untouched response, so nothing is lost in flattening.

Frequently asked questions

What does a reverse phone lookup API return?

It returns the identity behind a phone number: the name of the person or business who holds it, their age range and gender, the addresses linked to them, how long the number has been linked to that person, and the metadata on the line itself, which is the line type, the carrier, whether the line is prepaid, whether it is commercial and whether it is valid at all.

How do I catch a reassigned phone number?

Use reverse phone rather than caller identification, and read the rows it returns. Caller identification answers with a single owner. Reverse phone answers with every owner on record, each written as its own row with a linkToPhoneStartDate. A number that shows two owners with different link dates is a number that changed hands, and the most recent link date is the one you should be dialling.

What is a phone activity score?

A 0 to 100 score for how much recent evidence there is that a number is still in service. It is not the same as validity: a disconnected number can still be a perfectly valid, correctly formatted, correctly carriered number. On a list older than a few months the activity score is the field that separates numbers worth dialling from numbers that will never ring.

What is lead grading and when should I use it?

Lead grading takes one form submission, the name, phone, email, address and signup IP together, and grades each channel A to F while checking each one against the name given. Use it at the point of capture, before a lead reaches a rep. It answers a different question from validation: not is this phone number real, but does this phone number belong to the person who just typed it into your form.

How do I build a mobile-only SMS list?

Run phone validation or reverse phone over your numbers and set keepLineTypes to Mobile. Add a minActivityScore to drop numbers that no longer show signs of life, and switch on the litigator add-on with excludeLitigatorRisk so known TCPA litigators never reach the send.

What is TCPA litigator screening?

Some phone numbers belong to people who file Telephone Consumer Protection Act claims against businesses that call them. The litigator add-on flags those numbers before you dial. Switch it on under addOns and set excludeLitigatorRisk to drop the flagged rows entirely.

Can I find who lives at an address?

Yes. Reverse address returns the current residents of a postal address, one row per resident, with name, age range, gender, historical addresses and associated people. Address validation is the narrower check: whether the address is real, active, commercial and deliverable, with coordinates.

Do I need my own API key?

Yes. This actor does not include data access. You use your own API key from Trestle, which is the provider whose identity data API this actor calls, created on their developer dashboard. Your own plan, quota and terms apply. Paste the key into the apiKey field, where it is stored as an Apify secret, or supply it as the DATA_API_KEY environment secret.

What happens when a number or an address returns nothing?

The row is written with found: false and an error giving the reason, and the run continues to the next input. Partial failures are kept rather than discarded: this provider answers a lookup that resolved the phone but not the email with HTTP 200 carrying an error object and a warnings list, and both are preserved on the row as partialError and warnings. Misses are never charged for. 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 lead, phone owner, phone record or resident resolved into the dataset, and never for misses, for rows dropped by the quality filters, or for duplicates. Apify platform usage is included in the per-result price. Note that reverse phone and reverse address can return more than one row per input, since a number can have several owners and an address several residents. Your own API provider's quota is separate and billed by them.

Keyword map

reverse phone lookup API, caller ID API, phone validation API, phone number verification, line type lookup, carrier lookup, CNAM lookup, phone activity score, disconnected number detection, reassigned number check, TCPA litigator screening, lead verification API, lead grading, contact validation API, reverse address lookup, address validation API, identity verification data, people search by phone, mobile number lookup, contact data enrichment