People Search API (Person Data API)

What it means

People search APIs — the category also goes by person data API — sit at the intersection of consumer "find a person" sites and B2B contact-data providers. They differ from B2B enrichment APIs (Clearbit, Apollo) because they're built around residential identity — the person at home — rather than work email and job title.

What a person data API returns. A typical response resolves your input to a single individual and carries:

• Identity attributes — full name and common aliases, sometimes an age band.
• Phones — with line type (mobile vs. landline) and a last-seen date indicating how recently the number was observed connected to that person.
• Emails — personal addresses, ranked by recency.
• Addresses — current and historical, which is how you confirm the match is the right John Smith.
• Related persons — spouses, relatives, and associates, on providers that expose an identity graph.

How developers integrate one. The pattern is consistent across the category: authenticate with a Bearer token, POST a JSON body containing the name plus disambiguators (address, city, state), and branch on the response — a match maps into your CRM or dialer fields; a miss (matchFound: false) gets logged and, under per-match pricing, costs nothing. Single-record endpoints handle webhook-driven enrichment; list workloads move to an async bulk endpoint (upload a CSV, poll status, download results). A published OpenAPI spec is worth checking for early — it means you can generate a typed client instead of hand-writing one.

Key things to evaluate before committing to a person data API:

• Pricing model. Per-match billing (no charge on a miss) is dramatically better than per-query billing for any workflow with a non-trivial miss rate.
• Refresh cadence. Monthly snapshots produce stale phones; daily refreshes catch disconnects sooner.
• Rate limits and async bulk. A 60 req/min synchronous endpoint is fine for CRM enrichment; CSV upload with async polling is required for list processing.
• Response depth. If your workflow ever needs the household — not just the individual — pick a provider whose graph includes relatives and associates rather than bolting on a second vendor later.

A people search API is a REST endpoint that takes identifying details about a person — at minimum a last name, usually paired with a city, state, ZIP or street address — and returns the contact data attached to that identity: phone numbers, email addresses, and the addresses on file for them. The category is also sold as a person data API. Both names describe the same thing: programmatic access to residential identity, as distinct from the work identity — company, job title, corporate email — that a B2B enrichment API such as Clearbit or Apollo resolves.

Two very different products answer to "people search," and separating them is the first job for anyone evaluating vendors.

Ava Data is the second kind. There is no public profile page, no directory to browse, and no way to look a stranger up from a phone number that appeared on your screen — the API keys on a name plus a location and answers over HTTP, for software. If what you want is a person report to read, this is the wrong product. If you have a record in a CRM, a spreadsheet of owners, or a queue of accounts and you need working contact details written back onto them, this is exactly it.

The input contract

Both search endpoints take a JSON body and a bearer token against the base URL https://app.avadata.ai/api/v1.

• POST /standard-search requires two fields: lastName and dataTypes, an array of one or both of "phone" and "email". firstName, address, city, state and zip are optional and are what narrow the answer to the right individual.
• POST /deep-search requires lastName only and takes no dataTypes — there is no selector, so the response shape is fixed: a subject plus a related-persons array.

That is the whole surface of the search request, and its shape defines the boundary of the product. Neither request schema has a property that accepts a phone number, an email address, or a person identifier as the search key, so there is no reverse lookup — the phone number lookup API page covers forward versus reverse in detail. lastName carries a minLength of 1 on both endpoints, so there is no address-only search either: resolve the owner's name first, then trace. Search is synchronous at 60 requests per minute per key; a list goes through the asynchronous bulk CSV endpoints instead.

The output shape

Every response is wrapped as { "success": true, "data": { ... } }. Read data.matchFound before anything else.

A Standard Search match carries a flat nullable name string — not split into first and last — plus creditsCharged, an addresses array of { street, city, state, zip } objects, and a nullable matchType whose values the spec does not enumerate. The phones and emails arrays are present only when that data type was requested and a match was found, so treat both as optional. Each phone is an object of exactly number and type; each email is an object of exactly address. There is no last-seen date on a phone, no ordering or ranking defined for emails, and no flag on the address array marking which address is current — it is simply the addresses on file, with no current-versus-prior label, and confirming you have the right John Smith is done by matching those addresses against what your own record already holds.

A Deep Search match returns a different shape: a subject object that splits firstName and lastName and adds aliases, an integer age, dob, deceased and bankruptcy, plus a relatedPeople array where each entry carries a relationship label such as Spouse. Nothing in any response carries a persistent person ID, and no endpoint retrieves a person by one — every call is a stateless, point-in-time answer keyed by the identity you sent in. Field-by-field reference for all ten operations lives in the API reference, and the graph itself is explained on relational mapping.

What a lookup costs

Pricing is per match, not per query. dataTypes: ["phone"] or ["email"] costs 1 credit (2¢); ["phone","email"] costs 2 credits (4¢); a Deep Search costs 10 credits (20¢). When no match is found the endpoint still returns HTTP 200, with matchFound: false and creditsCharged: 0 — a miss is not an error and is not billed. The entry plan is $9/month with 100 credits, which is enough to build and test an integration end to end. For the same lookups on an entire list rather than one record, see the skip tracing API; for wiring results back onto CRM records, see contact enrichment.

The line this API does not cross

The distinction between a consumer people-search site and a business people search API is also the compliance boundary, so it is worth stating plainly. Ava Data is not a consumer reporting agency, and its data is not a consumer report under the Fair Credit Reporting Act. It may be used to locate and contact a person. It may never be used to decide anyone's eligibility for credit, insurance, employment, housing or tenancy, or a government licence or benefit — section 3 of the Terms of Service bars all of it, and the same section bars using the service to stalk, harass or intimidate anyone, or to locate a person in violation of a protective or restraining order. Outreach is the caller's responsibility too: the API returns contact information, it does not place calls or screen numbers against do-not-call registries.

Person data API vs. people search API: which slice this one is

"Person data" is the wider of the two labels. A person data API can mean any of three different products, and vendors rarely say which one they are selling:

• Identity resolution — collapsing scattered records into one canonical entity that keeps a persistent ID across calls, so a warehouse can maintain a golden record. Ava Data does not do this. No response field in the spec carries an entity key and no endpoint retrieves a person by ID; the reasoning is set out on the contact enrichment API page.
• Demographic and attribute append — income bands, household composition, education, propensity and lifestyle scores, or the firmographic side (job title, employer, work email) that B2B tools like Clearbit and Apollo sell. Ava Data returns almost none of this. The only person-level attributes in the spec are age, dob, deceased, bankruptcy and aliases, and all five appear on Deep Search only.
• Contact and locate data — the phones, emails, addresses and household connections attached to one named individual. This is the slice Ava Data covers, and it is what the people search API category has always meant: you send a name plus disambiguators and get back the ways to reach that person.

So the accurate description is narrow on purpose. Ava Data is a person data API for personal contact and location data — the phones, emails, addresses and adjacent people attached to one individual, not their employer and not a demographic profile of them. If your requirement is a durable ID, a household income model, or a work email, this is the wrong endpoint and no amount of parameter-tuning changes that.

What a single person data API response actually contains

Every field below is a real property name from the published OpenAPI 1.1.0 spec — nothing is inferred from marketing copy. Standard Search costs 1 credit (2¢) per data type and returns contact channels; Deep Search costs 10 credits (20¢) and returns a structured subject plus the related-people graph.

Two details trip people up. The array is relatedPeople, not relatedPersons — the schema is named RelatedPerson but the response property is plural-people, and how that graph is walked is covered separately. And age is an exact integer alongside a nullable dob string, not an age band. Field-by-field request and response reference for all ten operations lives in the API docs.

What this person data API does not return

Naming the gaps is faster than discovering them in integration:

• No persistent person ID. Every search is a stateless, point-in-time answer. The only identifiers in the spec belong to jobs and log entries — jobId and lookupId on a bulk or audience upload, and the activity id on GET /usage — never to a human.
• Nothing on a phone beyond the number and a free-text type string. No carrier, no caller-ID name, no ported or line status, no last-seen date — see the phone lookup page for why.
• Nothing on an email beyond the address. No deliverability verdict, no recency, and the spec promises no ordering, so treat the array as unranked.
• No current-versus-historical flag on an address. The four address strings carry no date and no current marker; use the ones you already trust as confirmation the match is the right individual.
• No demographics, no firmographics. No income, homeownership score, education, propensity model, job title or work email.
• No lookup by phone number and none by address alone. lastName is required on both search endpoints, so the input is always a named person.

Ava Data is not a consumer reporting agency and this data is not a consumer report. The deceased and bankruptcy booleans exist to route business outreach — skip a decedent, prioritise a file — and must never be used to decide anyone's eligibility for credit, insurance, employment or housing.

What businesses use a people search API for

A people search API is a component inside a business system, not a consumer lookup site. The consumer version of "people search" is a web page where anyone types in a name and reads what comes back about a private individual. A person data API is the opposite shape: a key issued to a business account, called by that business's own software, billed per match, and bound by the account's terms. Every workflow below starts with a record the business already holds — a property file, an account in a ledger, a lead in a CRM, a row in a customer's own database — and ends with a phone number or email that lets the business reach the person attached to it.

One limit applies to all four without exception. Ava Data supplies the locate step. It is not a consumer reporting agency and its data is not a consumer report, so it may be used to find someone — never to decide their eligibility for credit, insurance, employment, or housing. Section 3 of the Terms of Service also bars using it to locate a person in violation of a protective or restraining order.

Real-estate investors and wholesalers

The starting record is a property, not a person: a county file gives an owner name of record and a mailing address that has stopped reaching anyone. The API turns that into something dialable — POST /standard-search with the owner name plus the property address, dataTypes: ["phone"] at 1 credit (2¢) or ["phone","email"] at 2 credits (4¢), charged only when a match comes back. A whole pull goes through the asynchronous bulk CSV path instead of a loop: upload a file with an address column and the same dataTypes selection (name, city, state and zip columns sharpen the match), poll the job, download the results. When the owner's own number leads nowhere, a 10-credit Deep Search adds the related-persons graph. The mechanics of that tier live on the skip tracing API page; the list side lives on absentee-owner and tax-delinquent pulls.

Debt collectors and recovery teams

Collections is the oldest use of this category and the most tightly scoped. The account already carries a name and a last-known address; what it no longer carries is a number that reaches the account holder. The API returns the phone numbers and email addresses it has on file for that person so the account can be worked at all — that is the locate step, and it is the whole of what Ava Data does here. What a collector may say once the call connects, particularly to a third party, is governed by federal law rather than by any data provider; the skip tracing page covers that boundary. The same sentence bears repeating in this context because it is the one that matters: the data may be used to find a person, never to decide their eligibility for credit, insurance, employment, or housing.

Realtors and agent teams

Agents work lists of owners — a geographic farm, an expired-listing pull, an FSBO sweep, a sphere-of-influence file that has aged. Those records reliably carry an address and reliably lack a phone. A Standard Search on name plus address fills that gap before the mailer goes out, and the results write into the CRM the team already runs; Follow Up Boss is the one live integration, so a lead can be traced from a CRM automation with no code. A separate endpoint, POST /audience/upload, takes a contact CSV — an email or phone column, or a name plus address, city, state and zip — and returns ready-to-upload files appended with hashed identifiers for ad-platform custom audiences, which is how the same farm list becomes a paid-social audience rather than only a call list; see Digital Matching. This is outreach to property owners as prospective clients. It is not tenant screening, and it is not a way to evaluate a buyer or a renter.

API developers and product teams

Developers are usually not the end user of the lookup at all — they are building the thing the other three audiences click. A person data API is attractive in that position because the surface is small and the billing is predictable: bearer auth against https://app.avadata.ai/api/v1, two synchronous search endpoints returning plain JSON, a documented 60 requests per minute per key, an asynchronous bulk path for lists, and GET /credits to check the balance before a large run. Cost tracks matches rather than calls, so an enrichment queue full of thin records does not quietly bill for its own failures. One design constraint shapes every integration: no response carries a person identifier and no endpoint retrieves a person by one, so your own record ID stays the identity spine — the contact enrichment API page works through that pattern, and the API reference and OpenAPI spec carry the field-level detail.

What it is not used for

Three exclusions are worth stating outright, because "people search" as a phrase invites all three. There is no reverse lookup — neither search endpoint takes a phone number as an input, and lastName is required on both, so you cannot start from a number and ask who owns it (the phone lookup page covers that distinction in full). There is no eligibility use — credit, insurance, employment, housing and tenant screening are FCRA-regulated purposes and are barred by the Terms. And there is no consumer directory: access is an API key on a business account, billed per match, for reaching people your business already has a record of. A private individual looking up another private individual is not what this is built for, and it is not what it is sold for.

How Ava Data handles people search api (person data api)

Ava Data's API is a person data API in exactly this mold: REST endpoints returning standard JSON, Bearer-token authentication, documentation with request and response examples, and a downloadable OpenAPI spec (API version 1.1.0) you can generate clients from. Pricing is per match — 1 credit (2¢) for a phone-only lookup, 2 credits (4¢) for phone + email, and 10 credits (20¢) for a Deep Search that adds the relatives-and-associates graph — and you pay nothing on a miss. The synchronous endpoint runs at 60 requests per minute; list workloads use the asynchronous bulk CSV upload with status polling. The underlying identity graph refreshes every 24 hours.

If you don't need the API at all, the same data is available in the Ava Data dashboard — search by name and address, get a contact card, export to CSV — and Follow Up Boss users can trigger the same lookups from CRM automations without writing code. The API is for teams wiring person data into a CRM, dialer, or AI pipeline; the $9/month plan (100 credits included) is enough to build and test an integration end to end.

For developers: example API call

If you'd rather click than code, the Ava Data dashboard returns the same data without a single line of JSON. The snippet below is for teams wiring Ava Data into a CRM, dialer, or AI pipeline.

{
  "firstName": "John",
  "lastName": "Smith",
  "city": "Austin",
  "state": "TX",
  "dataTypes": ["phone", "email"]
}

{
  "success": true,
  "data": {
    "matchFound": true,
    "creditsCharged": 2,
    "name": "John Smith",
    "phones": [{ "number": "5125551234", "type": "mobile" }],
    "emails": [{ "address": "john@example.com" }]
  }
}

Related terms

• Skip Tracing — Skip tracing is the process of locating a person's current contact information — phone numbers, email addresses, and known associates — by stitching together public records, utility data, and proprietary identity graphs.
• CRM Enrichment — CRM enrichment is the process of automatically appending missing fields — phone, email, mailing address, related persons — to records already in your CRM, usually via webhook or scheduled batch job.
• Batch Skip Tracing — Batch skip tracing — also called bulk skip tracing — runs a skip trace over a whole list of records at once, typically a CSV of names and addresses, and returns matched contact information as a downloadable file or through an async API.

Frequently asked questions

What fields does a people search API request require?

Ava Data requires lastName on both search endpoints, plus dataTypes — phone, email, or both — on /standard-search. firstName, address, city, state, and zip are optional inputs that narrow the identity to one person instead of many. Deep Search takes no dataTypes. A request missing lastName is rejected with 400 rather than searched.

Can I query a person data API by phone number instead of a name?

No. Every Ava Data search keys on identity: lastName is required on /standard-search and /deep-search, and neither request schema has a field that accepts a phone number, an email address, or a person ID as the lookup key. Phone numbers are something the response returns, never something the request takes.

How is a people search API different from a consumer people-search website?

A people search API is built for business systems: an authenticated REST call returns JSON that a CRM, script, or batch job consumes, priced per match. Consumer people-search sites sell subscription lookups to individuals. Ava Data is not a consumer reporting agency — its data locates a person for business outreach, never to decide credit, insurance, employment, or housing eligibility.

What does a person data API response actually contain?

A Standard Search response returns matchFound, creditsCharged, a nullable name string, matchType, addresses[], and — for the data types requested — phones[] with number and type, plus emails[] with address. Deep Search instead returns a subject object and relatedPeople[], each with a nullable relationship label such as Spouse. No carrier, line status, or confidence field exists in either schema.

Does a people search API charge for a lookup that finds nobody?

Not at Ava Data. A search with no match returns HTTP 200 carrying matchFound: false and creditsCharged: 0, so you pay only for records that actually come back. A match costs 1 credit (2¢) per data type on Standard Search — 4¢ for phone plus email — and 10 credits (20¢) on Deep Search.

I only have a property address — can a person data API find the owner?

Not from the address alone. lastName is required, so an address with no name attached is not a valid query; address, city, state, and zip only sharpen a name-based search. Pull the owner of record from the county assessor or deed file first, then search that name together with the property address.