Search People

Search the DealMachine people/contacts database using filters. Control which fields are returned, how results are paginated and sorted.

Filters must come from the people catalog. To gate an audience on property attributes, use Search Properties with anchor: "people", which returns the people connected to the matching properties.

This endpoint builds audiences from filters and locations. It does not accept a person's name as a filter. To look up a specific person by first and last name, use Enrich by Name, POST /v1/enrichment/name, or dm enrich name.

Body Parameters

body locationsarray

Array of location objects defining where to search. Required unless filters or protocol filters are provided (max 15). Locations use OR logic — results matching any location are included.

Location object properties

body typestringrequired

Location type: state, county, city, zip_code, radius, or polygon.

body codestring

Location identifier. Required for state (2-letter abbreviation, e.g., "TX"), county (5-digit FIPS code, e.g., "29189"), city (place ID, e.g., "7333"), and zip_code (5-digit ZIP, e.g., "63101").

body latitudenumber

Center point latitude. Required for radius.

body longitudenumber

Center point longitude. Required for radius.

body radius_milesnumber

Search radius in miles. Required for radius.

body coordinatesarray

Array of [longitude, latitude] pairs defining the boundary. Required for polygon (minimum 3 points).

body filtersarray

Array of filter objects. Required unless locations or protocol filters are provided. All filters must come from the people catalog (source_type=people) — see People Filters. Property filters are rejected with filter_source_mismatch; use the property endpoints for those.

Filter object properties

body filter_idstringrequired

The filter slug from the List Filters endpoint (e.g., has_active_phone_number, estimated_household_income).

body operatorstring

One of the filter's allowed_operators. See Filter Values for all operators by type. Optional for BOOLEAN filters — automatically defaults to is_boolean.

body valueanyrequired

The filter value. Shape depends on the operator — can be a number, string, boolean, array, or object. See Filter Values.

body include_listsobject

Restrict results to people list IDs, for example { "people_list_ids": [123] }.

body exclude_listsobject

Exclude people list IDs, for example { "people_list_ids": [456] }.

body exclude_previously_exportedboolean | object

Exclude people already exported by your organization. Pass true for defaults or a full Query Builder export exclusion object.

body bigquery_data_environmentinteger

Query Builder dataset environment: 1 production, 2 staging, 3 development.

body fieldsstring[]

Field IDs to include in results. Can include both people and property fields — the source restriction applies to filters, not to fields. Omit or pass an empty array for the default set. Use person_coordinates to select both person_latitude and person_longitude, or coordinates to select both property coordinate values.

This endpoint filters using the people catalog only. Property attributes such as estimated_value, property_type or num_units return filter_source_mismatch. To build an audience from property criteria, use Search Properties with anchor: "people" and a contact_audience. property_match applies to Export People only.

body pageintegerdefault: 1

Page number (min: 1).

body per_pageintegerdefault: 25

Results per page (min: 1, max: 250).

body sortarray

Array of sort objects for ordering results. See Pagination & Sorting.

Sort object properties

body field_idstringrequired

The field to sort by.

body directionstringrequired

asc (ascending) or desc (descending).

body estimate_costboolean

When true, returns a credit cost estimate without returning data or consuming credits. See Cost Estimate.

Response

Every search response contains four top-level keys: data, totals, credits, and pagination. See Credits for full details on how credits work.

`data`

An array of person objects. Each person includes the always-included people fields — name, phones, emails, and primary address — plus any fields you requested. Requested property fields are returned flat on the person object. Credits are consumed per entity.

1234567891011121314151617181920{
  "dm_person_id": "per_x1y2z3",
  "full_name": "John Smith",
  "first_name": "John",
  "last_name": "Smith",
  "middle_initial": null,
  "suffix": null,
  "phones": [
    { "number": "5125551234", "type": "wireless", "do_not_call": false, "carrier": "Verizon Wireless" },
    { "number": "5125559999", "type": "landline", "do_not_call": false, "carrier": null }
  ],
  "emails": [{ "address": "john.smith@example.com" }],
  "address": "456 Oak Lane",
  "city": "Austin",
  "state": "TX",
  "zip": "78701",
  "full_address": "456 Oak Lane, Austin, TX 78701",
  "estimated_value": 875000,
  "estimated_equity_percentage": 72
}

Each phone carries number, normalized type, do_not_call, and carrier — see Phones.

To retrieve the full set of properties associated with one person, use Get Person with include_properties=true. Search responses do not nest a properties array.

`totals`

The full count of matching entities across the entire result set, regardless of pagination.

123456{
  "totals": {
    "people": 412,
    "properties": 387
  }
}

Field	Type	Description
`people`	integer	Total people matching the filters
`properties`	integer	Total properties the matched people are connected to.

`credits`

A breakdown of what this request cost. Included on every search response.

12345678{
  "credits": {
    "used": 25,
    "properties": 0,
    "people": 25,
    "deduplicated": 0
  }
}

Field	Type	Description
`used`	integer	New credits charged after deduplication
`properties`	integer	Property lead records evaluated in this response
`people`	integer	People lead records evaluated in this response
`deduplicated`	integer	Entities already accessed this billing period (free)

Credits are deduplicated within your billing period. If you've already accessed a person or property this month, it won't be charged again — it shows up in deduplicated instead.

`pagination`

Field	Type	Description
`page`	integer	Current page number
`per_page`	integer	Results per page
`total_results`	integer	Total matching records (always equals `totals.people`)
`total_pages`	integer	Total pages available
`has_next_page`	boolean	Whether more pages exist after this one
`has_previous_page`	boolean	Whether pages exist before this one

Filtering on Property Criteria

filters on this endpoint resolve against the people catalog only. A property filter returns HTTP 400 with code filter_source_mismatch; when an equivalent people filter exists, the response's details.replacementFilterId names it.

To build an audience from property criteria, start from the property side instead:

Goal	Endpoint
People matching people criteria	`POST /v1/people/search` (this endpoint)
People connected to properties matching property criteria	`POST /v1/properties/search` with `anchor: "people"` and a `contact_audience`
Counts only, before spending credits	`POST /v1/properties/search/count` — returns distinct people alongside the property count

contact_audience on the property endpoints (owners, owners_and_family, residents, renters) selects the person-to-property relationship.

Notes

At least one location, filter, list condition, or previous-export condition is required. An empty filters array is valid when another search criterion is present.
All filters are combined with AND logic. See Searching.
Filters must all come from the people catalog; property filters return filter_source_mismatch. The fields you request are not restricted this way.
All search results are enriched and consume credits per entity. Use estimate_cost: true to preview credit costs before searching.
Use source_type=people and source_type=properties when calling List Filters and List Fields to discover available filters and fields.

Cost Estimate

Set estimate_cost: true to preview the credit cost of a search before committing to it. The request is validated identically to a real search — same filters, same pagination — but no data is returned and no credits are consumed.

1234567891011121314curl -X POST "https://api.v2.dealmachine.com/v1/people/search" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "estimate_cost": true,
    "locations": [
      { "type": "state", "code": "TX" }
    ],
    "filters": [
      { "filter_id": "estimated_household_income", "operator": "greater_than", "value": 100000 }
    ],
    "page": 1,
    "per_page": 25
  }'

The response contains totals, pagination, and estimated_credits — but no data array:

123456789101112131415161718192021222324{
  "totals": {
    "people": 412,
    "properties": 387
  },
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_results": 412,
    "total_pages": 17,
    "has_next_page": true,
    "has_previous_page": false
  },
  "estimated_credits": {
    "this_page": 25,
    "total_all_pages": 412,
    "breakdown": {
      "people": 25,
      "properties": 0,
      "already_accessed": 0,
      "note": "Estimate based on total results. Actual credits may be lower due to deduplication within your billing period."
    }
  }
}

Field	Type	Description
`estimated_credits.this_page`	integer	Estimated credits for this page before deduplication
`estimated_credits.total_all_pages`	integer	Credits all pages combined would consume
`estimated_credits.breakdown.people`	integer	People data credits on this page
`estimated_credits.breakdown.properties`	integer	Property credits; currently `0` for people search
`estimated_credits.breakdown.already_accessed`	integer	Currently `0`; final usage applies billing-period dedup

Cost estimate is free and does not consume credits. Use it as often as needed. To get just the total count without cost estimates, use Count People.

Request example

12345678910111213141516171819202122232425262728293031curl -X POST "https://api.v2.dealmachine.com/v1/people/search" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      { "type": "state", "code": "TX" }
    ],
    "filters": [
      {
        "filter_id": "estimated_household_income",
        "operator": "greater_than",
        "value": 100000
      },
      {
        "filter_id": "has_active_phone_number",
        "value": true
      }
    ],
    "fields": [
      "full_name",
      "phones",
      "emails",
      "estimated_value",
      "estimated_equity_percentage"
    ],
    "page": 1,
    "per_page": 25,
    "sort": [
      { "field_id": "full_name", "direction": "asc" }
    ]
  }'

Response example

123456789101112131415161718192021222324252627282930313233343536373839{
  "data": [
    {
      "dm_person_id": "per_x1y2z3",
      "full_name": "John Smith",
      "first_name": "John",
      "last_name": "Smith",
      "phones": [
        { "number": "5125551234", "type": "wireless", "do_not_call": false, "carrier": "Verizon Wireless" }
      ],
      "emails": [{ "address": "john.smith@example.com" }],
      "address": "456 Oak Lane",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "full_address": "456 Oak Lane, Austin, TX 78701",
      "estimated_value": 875000,
      "estimated_equity_percentage": 72
    }
  ],
  "totals": {
    "people": 412,
    "properties": 387
  },
  "credits": {
    "used": 25,
    "properties": 0,
    "people": 25,
    "deduplicated": 0
  },
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_results": 412,
    "total_pages": 17,
    "has_next_page": true,
    "has_previous_page": false
  }
}