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.

Refetch(er)

Contact sales →

Contact data · United States · Access on request

True People
Search API

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.

Resolve a name, phone number or address into a structured US contact record — current and prior addresses, phone numbers, emails and known relatives — as normalized JSON across two endpoints: search and detail. Batch up to 30 lookups per request.

Contact sales → Read the docs

US coverage Name, phone & address lookups Up to 30 per request

3 lookup types · 30 queries per request · normalized JSON · US coverage · billed per lookup

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.

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

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. Use depth: "basic" for the fastest search cards or depth: "contact" to return full contact records in one request. You can also pass a match's detailUrl to /people-detail. Response examples below are abbreviated and use illustrative data.

POST /people-search

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

// → 200 OK
{
  "success": true,
  "results": [
    {
      "success": true,
      "query": { "id": "lead-91", "name": "Jordan Avery", "city": "Plano", "state": "TX" },
      "totalMatches": 1,
      "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_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      { "detailUrl": "https://www.truepeoplesearch.com/find/person/…" }
    ]
  }'

// → 200 OK
{
  "success": true,
  "results": [
    {
      "success": true,
      "query": { "detailUrl": "https://www.truepeoplesearch.com/find/person/…" },
      "totalMatches": 1,
      "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"],
          "phoneDetails": [
            { "number": "(972) 555-0148", "type": "Wireless" },
            { "number": "(214) 555-0102", "type": null }
          ],
          "jobTitle": "Operations Manager",
          "jobTitleStatus": "available",
          "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`.
`depth`	string	`basic` (default) for search cards or `contact` for full contact records.
`maxDetailPagesPerQuery`	number	Contact-depth cap on detail lookups and returned checked matches, from `1` to `10`. Defaults to `maxResultsPerQuery`; unchecked search cards are omitted.
`matchMode`	string	`all` (default) or `best` for the first provider-ranked match.
`fields`	string[]	Return only selected match fields.
`filters`	object	Filter by age, city/state/ZIP, and availability of phones, emails, addresses, or relatives.
`timeoutMs`	number	Default and maximum `295000` (295 seconds). Contact-depth search shares this budget across search, details, and retries. Basic search and standalone detail use it per worker attempt; allow extra client-side time for network overhead.
/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 · object	Reverse-address lookup. Free-form address or an object with street, city, state, and postal code.
`city`	string	Narrows a name search to a city.
`state`	string	Two-letter US state code, e.g. `TX`. Case-insensitive on input.
`postalCode`	string	Five-digit ZIP or ZIP+4. `zip` is accepted as an alias.
`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. Optional fields may be omitted. Metadata uses explicit empty values: jobTitle: null when unavailable, phoneDetails: [] when there are no returned numbers, and type: null for an unknown phone type. A fields selection omits unselected match fields.

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	Successfully completed queries, including searches with zero matches.
`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`.
`totalMatches`	number	Provider matches before response filters and `matchMode`.
`matchCount`	number	Matches returned after response filters and `matchMode`.
`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).
`phoneDetails`	object[]	Each `{number, type}` pairs a returned number with its source-reported `Wireless`, `Landline`, or `VoIP` label. Type is `null` when unknown or conflicting; formatting-equivalent US numbers are deduplicated. The existing `phoneNumbers` array is unchanged.
`jobTitle`	string · null	Explicit source-provided job title or occupation for the matched person, or `null` when unavailable. Employment data is not guaranteed. Selecting this field or `phoneDetails` on search automatically fetches detail data.
`jobTitleStatus`	string	`available`: title provided; `not_available`: no usable title for this result, with `jobTitle: null`. A missing title does not mean unemployed. Failed detail lookups remain errors. Selecting this field fetches detail data; select both this field and `jobTitle` to receive the title and its availability.
`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.

Integration guide

Add job titles and phone types.

Your existing API key, endpoints, phoneNumbers, and emails stay unchanged. Read the new fields from each results[].matches[] record and add them to your export. Existing scripts and spreadsheets do not gain columns automatically.

Fetch detail data before deciding it is unavailable

Use /people-detail with the selected search match's detailUrl, or use /people-search with depth: "contact". Selecting phoneDetails, jobTitle, or jobTitleStatus also activates contact depth. Basic search alone does not check this metadata; selecting only phoneNumbers does not trigger a detail lookup. Job metadata comes from the same person-detail page, not a separate employment subpage.

Contact-depth search uses the same pool-first detail lookup as /people-detail, with a backup for retryable failures. Only checked matches up to maxDetailPagesPerQuery are returned; filters and matchMode apply afterward. totalMatches preserves the provider count before those controls. If a required detail lookup fails, that query returns success: false and an error instead of presenting missing contacts or an unavailable job title as a successful lookup. Other queries in the batch may still succeed.

If you already send fields, add the new names while retaining every field you still need. The selection replaces the returned match fields; it does not add to the defaults. Keep detailUrl when you need a follow-up detail lookup.

POST /people-detail · request body

{
  "queries": [
    { "detailUrl": "https://www.truepeoplesearch.com/find/person/…" }
  ],
  "fields": ["name", "phoneNumbers", "phoneDetails",
    "jobTitle", "jobTitleStatus", "emails", "detailUrl"]
}

API value	Suggested display / export
`jobTitle` + `jobTitleStatus: "available"`	Show the returned title in your Job Title column.
`jobTitle: null` + `jobTitleStatus: "not_available"`	Show `Not available`. This is not a claim that the person is unemployed; employer/company names are not substituted for a job title.
`phoneDetails[].number` + `phoneDetails[].type`	Show the number with its source-reported `Wireless`, `Landline`, or `VoIP` type. Display `Unknown` for a `null` type.

Not available and Unknown are display labels, not literal API values. Read each {number, type} pair together: do not join phoneNumbers and phoneDetails by array index, because phoneDetails deduplicates formatting-equivalent US numbers.

Python · export-column mapping

# For each match in a successful, detail-enriched result.
# Include all fields used below in fields, or omit fields entirely.
row = {
    "phones": " | ".join(match.get("phoneNumbers") or []),
    "phone_details": " | ".join(
        f"{p['number']} ({p.get('type') or 'Unknown'})"
        for p in (match.get("phoneDetails") or [])
    ),
    "job_title": match.get("jobTitle") or "Not available",
    "job_title_status": match["jobTitleStatus"],
}

Merge these columns into your existing row, keep your other columns, and rerun the export. Check results[].success first: a failed detail lookup must remain an error, not be converted into Not available. A successful query with no matches is a no-match result, not a person record with a missing title.

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.