# Reverse Phone Lookup API - Caller ID, Owner and Address Data (`nabeelbaghoor/reverse-phone-lookup-api`) Actor

Find the person or business behind a phone number, with line type, carrier and an activity score that separates a live number from a disconnected one. Grade inbound leads across phone, email and address, screen for TCPA litigators, and list the residents of an address. Pay per result.

- **URL**: https://apify.com/nabeelbaghoor/reverse-phone-lookup-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Developer tools, Lead generation
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$15.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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

```json
{
  "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

# Actor input Schema

## `mode` (type: `string`):

Lead grading scores a whole lead at once: the phone, the email and the address are each graded A to F and checked against the name on the form. Phone validation returns line type, carrier and an activity score that tells a disconnected number from a live one. Caller identification and caller name return the owner behind a number. Reverse phone returns every owner on record, which is how a reassigned mobile is caught. Reverse address returns the current residents of a postal address. Address validation checks an address is real and deliverable.

## `phones` (type: `array`):

Phone numbers, one per line, in international format or in the local format of the country you set below. Used by every phone product, and by lead grading as the phone half of each lead.

## `names` (type: `array`):

The name each lead gave you, one per line. Lead grading reads the lists row by row rather than crossing them, so row one of this list belongs with row one of every other list: one row is one lead. Lead grading only.

## `emails` (type: `array`):

The email address each lead gave you, one per line, in the same order as the names. Graded for deliverability and checked against the name. Lead grading only.

## `addresses` (type: `array`):

Postal addresses, one per line, written as one line each. Reverse address and address validation read this list as the thing to look up; lead grading reads it as the address half of each lead, in the same order as the names. A single line is split into street, city, state and postal code before the request.

## `ipAddresses` (type: `array`):

The IP address each lead submitted the form from, one per line, in the same order as the names. Returns a trust score and how far the IP sits from the address given, which is what separates a local lead from one filled in from another continent. Lead grading only.

## `businessNames` (type: `array`):

The business name each lead gave you, one per line, in the same order as the names. Use it when the lead is a company rather than a person. Lead grading only.

## `countryCode` (type: `string`):

Two letter ISO 3166 country code applied to the postal addresses above, for example US or CA. Leave empty to let the provider infer it.

## `countryHint` (type: `string`):

Two letter ISO 3166 country code used to read phone numbers written in local format, for example US. Numbers already in international format do not need it.

## `nameHint` (type: `string`):

A person or business name you already associate with the numbers, used to rank the owners the provider returns. Caller identification and reverse phone only.

## `postalCodeHint` (type: `string`):

A postal code you already associate with the numbers, used to rank the owners the provider returns. Caller identification and reverse phone only.

## `addOns` (type: `array`):

Extra checks the provider bills separately. Litigator screening flags numbers belonging to known TCPA litigators before you dial. Spam screening flags numbers reported as spam. The two email checks return deliverability and how long the address has existed. Each add-on is only sent to the products that accept it, so leaving them all on is safe.

## `keepContactGrades` (type: `array`):

Only keep leads whose phone graded one of these. Restricting to A and B is how a raw form dump becomes a call list. Leave empty to keep every grade. Applied after the provider answers, so it reduces dataset noise and Apify spend rather than provider credits.

## `keepLineTypes` (type: `array`):

Only keep rows whose phone is one of these line types. Keeping mobile only is how an SMS list is built; dropping VOIP is how throwaway numbers are filtered out. Leave empty to keep every line type.

## `minActivityScore` (type: `integer`):

Only keep rows whose phone activity score is at least this, on a 0 to 100 scale. The activity score is what separates a number still in service from one that was disconnected months ago. Leave empty to keep every score.

## `requireValidPhone` (type: `boolean`):

Skip any row the provider reported as an invalid phone number.

## `requireNameMatch` (type: `boolean`):

Skip rows where the provider says the number belongs to somebody other than the name on the lead. Lead grading only.

## `excludeLitigatorRisk` (type: `boolean`):

Skip rows flagged as belonging to a known TCPA litigator. Needs the litigator screening add-on above to be switched on, since without it the provider never returns the flag.

## `skipNotFound` (type: `boolean`):

By default an input that resolved to nothing is still written, with found set to false and the reason on the row, so a list can be reconciled against what went in. Switch this on to leave those rows out entirely. Rows with no result are never charged for either way.

## `maxResults` (type: `integer`):

Stop after this many rows. Note that reverse phone and reverse address can return several rows per input, since a number can have several owners and an address several residents.

## `requestsPerMinute` (type: `integer`):

How fast to call the provider. Requests are spaced evenly rather than sent in bursts, which is what keeps a long list from bunching up against the rate limiter. Lower this if your plan has a tighter ceiling.

## `apiKey` (type: `string`):

Your own API key for the identity data provider this actor calls. The actor never ships a key: you bring yours, the run uses it, and it is stored encrypted. Can also be supplied as the DATA\_API\_KEY environment secret.

## Actor input object example

```json
{
  "mode": "realContact",
  "phones": [
    "+12065550100"
  ],
  "addOns": [],
  "keepContactGrades": [],
  "keepLineTypes": [],
  "requireValidPhone": false,
  "requireNameMatch": false,
  "excludeLitigatorRisk": false,
  "skipNotFound": false,
  "maxResults": 100,
  "requestsPerMinute": 300
}
```

# Actor output Schema

## `results` (type: `string`):

Graded leads, phone owners, phone metadata and address residents, one row each.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "phones": [
        "+12065550100"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/reverse-phone-lookup-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "phones": ["+12065550100"] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/reverse-phone-lookup-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "phones": [
    "+12065550100"
  ]
}' |
apify call nabeelbaghoor/reverse-phone-lookup-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/reverse-phone-lookup-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/FwiyoXdaZgLWlnZAX/builds/ciM8lMfXcTYESt8hF/openapi.json