How many lookups can I send in one request?

Up to 30 person queries per POST request. Each query is processed independently and billed as one lookup.

How do I get access to the People Search API?

Access is granted on request to vetted businesses. It is not part of the self-serve social scraper plans. Contact the Refetcher team with your use case to enable a key and discuss volume pricing.

True People Search API — Reverse Phone, Address & Name Lookup

Q: What does the True People Search API return?

For each matched person it returns name, approximate age, current city and state, current and prior addresses, phone numbers, emails, known relatives and a provider detail URL, as normalized JSON. Coverage is the United States.

Q: Can I search by phone number or address instead of a name?

Yes. Each query accepts a name, a phone number, or an address. Reverse-phone and reverse-address lookups are supported — provide at least one of name, phone or address per query.

What you get

A complete contact record,
from a single lookup.

Use /people-search to find matching records, then /people-detail to pull the deep details. The API returns the matching public records as clean JSON — no scraping, parsing or HTML to maintain. This is a contact-data service offered separately from Refetcher's social media scrapers.

US

Identity & location

Match a person and get their name, approximate age, current city and state, plus a history of current and prior addresses associated with the record.

nameagecurrent city/stateaddress history

US

Phones, emails & relatives

Each match includes known phone numbers, email addresses, and associated relatives — plus a provider detail URL for the underlying record.

phone numbersemailsrelativesdetail URL

The request

Simple to call.
Deep contact data.

Authenticate with one header and POST your search to /people-search. Grab the detailUrl from the best match, and pass it to /people-detail to extract the full contact record.

POST /people-search

# Resolve a person by name + state
curl -s https://api.refetcher.com/people-search \
  -H "X-API-Key: pc_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      { "id": "lead-91", "name": "Jordan Avery", "city": "Plano", "state": "TX" }
    ]
  }'

// → 200 OK
{
  "success": true,
  "results": [
    {
      "query": { "id": "lead-91", "name": "Jordan Avery", "city": "Plano", "state": "TX" },
      "matchCount": 1,
      "matches": [
        {
          "name": "Jordan M Avery",
          "age": 38,
          "currentCity": "Plano",
          "currentState": "TX",
          "summary": "Jordan M Avery is 38 years old and currently lives in Plano, TX...",
          "detailUrl": "https://www.truepeoplesearch.com/find/person/…"
        }
      ]
    }
  ]
}

POST /people-detail

# Extract the deep contact record using the detailUrl
curl -s https://api.refetcher.com/people-detail \
  -H "X-API-Key: pc_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      { "detailUrl": "https://www.truepeoplesearch.com/find/person/…" }
    ]
  }'

// → 200 OK
{
  "success": true,
  "results": [
    {
      "query": { "detailUrl": "https://www.truepeoplesearch.com/find/person/…" },
      "matchCount": 1,
      "matches": [
        {
          "name": "Jordan M Avery",
          "age": 38,
          "currentCity": "Plano",
          "currentState": "TX",
          "locations": ["4120 Maple Ave, Plano, TX 75074", "88 Birch Ln, Frisco, TX 75035"],
          "phoneNumbers": ["(972) 555-0148", "(214) 555-0102"],
          "emails": ["j.avery@example.com"],
          "relatives": ["Morgan Avery", "Taylor Avery"],
          "detailUrl": "https://www.truepeoplesearch.com/find/person/…"
        }
      ]
    }
  ]
}

Search by name, phone or address · Batch up to 30 queries · Response field reference ↓

Request

Query parameters.

The request body is a JSON object with a queries array (1–30 items). Each query must include at least one of name, phone or address. A bare name string ("queries": ["Jordan Avery"]) is also accepted.

Parameter	Type	Description
Request body
`queries` required	object[] · string[]	1–30 person queries. Each item is a query object (below) or a plain name string.
`maxResultsPerQuery`	number	Cap on matches returned per query. Default and maximum `10`.
`timeoutMs`	number	Per-request worker timeout. Default and maximum `150000`.
/people-search query — provide at least one of name, phone or address
`name`	string	Full name to search. Accepts `fullName` as an alias.
`firstName` / `lastName`	string	Used to build the search name when `name` is not supplied.
`phone`	string	Reverse-phone lookup. Any format; normalized to a 10-digit US number (a leading `1` is stripped).
`address`	string	Reverse-address lookup. Free-form street address.
`city`	string	Narrows a name search to a city.
`state`	string	Two-letter US state code, e.g. `TX`. Case-insensitive on input.
`age`	number	Approximate age (1–124) to disambiguate common names.
`id`	string	Your own correlation id. Echoed back on `query.id`; defaults to `q_1`, `q_2`, … when omitted.
/people-detail query
`detailUrl` required	string	The provider URL returned from a `/people-search` match. Required for `/people-detail`.

Response

Predictable responses,
field by field.

The top-level success is true only when every query in the batch succeeded — always inspect each result's own success flag. Fields a record does not expose are omitted rather than returned empty.

Field	Type	Description
Top level
`success`	boolean	`true` only if no query failed. Use per-result flags for partial batches.
`requestId`	string	Identifier for the request, useful when contacting support.
`summary.total`	number	Number of queries in the batch.
`summary.succeeded`	number	Queries that returned results.
`summary.failed`	number	Queries that failed.
`results`	object[]	One result per query, in request order.
`totalMs`	number	Total server processing time in milliseconds.
results[] — per query
`success`	boolean	Whether this individual query resolved.
`platform`	string	Always `people_search`.
`type`	string	Always `person_search`.
`provider`	string	Source of the record, e.g. `truepeoplesearch`.
`query`	object	The normalized query that was executed, including your `id`.
`matchCount`	number	Number of matches returned for this query.
`matches`	object[]	The matched person records (see below).
`searchedAt`	ISO 8601	When the lookup ran.
`workerMs`	number · null	Worker processing time for this query.
`error.category`	string	Failure category when `success` is `false` (see error reference).
`error.message`	string	Human-readable failure reason.
matches[] — search fields (/people-search)
`name`	string	Full name on the record.
`age`	number · null	Approximate age when available.
`currentCity`	string	Most recent known city.
`currentState`	string	Most recent known state.
`summary`	string	Short text summary of the match.
`detailUrl`	string	Pass this URL to the `/people-detail` endpoint.
matches[] — detail fields (/people-detail)
`name`	string	Full name on the record.
`age`	number · null	Approximate age when available.
`currentCity`	string	Most recent known city.
`currentState`	string	Most recent known state.
`locations`	string[]	Current and prior addresses (up to 8).
`phoneNumbers`	string[]	Associated phone numbers (up to 8).
`emails`	string[]	Associated email addresses (up to 8).
`relatives`	string[]	Known relatives and associates (up to 12).
`detailUrl`	string	Provider URL for the full underlying record.

Errors

Predictable failures.

A failed query never breaks the batch — it returns with success: false and an error.category. Transient categories are retried internally against a backup region before being returned. If every query fails the response status is 502.

Query error category	Meaning
`bad_query`	The query was invalid or unsearchable.
`timeout`	The lookup exceeded the worker timeout.
`rate_limited`	The upstream provider throttled the request.
`blocked_or_challenge`	The provider returned a challenge/CAPTCHA.
`challenge_timeout`	A provider challenge did not clear in time.
`navigation_timeout`	The provider page did not start loading in time.
`parse_error`	The provider returned an unreadable result page.
`network_error`	A transport error reaching the worker.
`upstream_error`	Temporary provider-side failure.
`worker_error`	The lookup worker failed before returning a result.
`unknown_error`	The lookup failed for an unclassified reason.

HTTP status	Meaning
`200`	At least one query in the batch succeeded.
`400`	Malformed body or no valid queries.
`401`	Missing or invalid API key.
`402`	Insufficient account balance for the request.
`405`	Method not allowed — use `POST`.
`502`	Every query in the batch failed.
`503`	Authentication or billing temporarily unavailable.

Use cases

Built for teams that need
to reach the right person.

Skip tracing & collections

Resolve stale contact details into current phone numbers and addresses for legitimate outreach, paired with relatives and address history.

reverse phoneaddress historyrelatives

Identity & record matching

Confirm a name maps to a real, consistent record before you act — disambiguate common names with city, state and age signals.

verificationdeduplicationmatch scoring

CRM & lead enrichment

Batch up to 30 records per request to append phones, emails and locations to your pipeline through one normalized endpoint.

batch enrichmentdata appendpipelines

Permissible use

Refetcher is not a consumer reporting agency and the True People Search API does not provide consumer reports. You may not use this data, in whole or in part, to make decisions about credit, employment, insurance, housing, tenant screening, or any other purpose regulated by the Fair Credit Reporting Act (FCRA) or equivalent laws. You are responsible for using the data lawfully and for honoring opt-out and privacy requests. Access is granted only for permissible business purposes.

Need access?tell us your use case & volume — we'll tailor pricing

Enabled for vetted businesses with a permissible use
Volume pricing, billed per lookup
Same key system as the rest of the Refetcher API

Contact sales →

Straight answers

People search, in plain English.

What does the True People Search API return? +

It has two endpoints. /people-search returns an array of matches with the person's name, age, city, and a short summary. /people-detail takes a match's detailUrl and returns the deep record: current and prior addresses, phone numbers, emails, and known relatives. Coverage is the United States.

Can I search by phone number or address instead of a name? +

Yes. Each query accepts a name, a phone, or an address — reverse-phone and reverse-address lookups are supported. Provide at least one of the three per query; city, state and age help disambiguate common names.

How many lookups can I send at once? +

Up to 30 person queries per POST. Each query is processed independently, returned in request order, and billed as one lookup.

How is this different from your social media scrapers? +

It is a separate, contact-data service. Our core business is the real-time social media scraper API; the True People Search API is offered on request to vetted businesses and is not bundled into the self-serve scraper plans.

How do I get access? +

Contact the Refetcher team with your use case and expected volume. Once approved, the endpoint uses the same API key system as the rest of Refetcher.

Is this data a consumer report under the FCRA? +

No. Refetcher is not a consumer reporting agency and this data is not a consumer report. It may not be used for credit, employment, insurance, housing, tenant screening, or any other FCRA-regulated decision. See the permissible-use note above.

True PeopleSearch API

A complete contact record,from a single lookup.