Search People

Search the DealMachine people/contacts database using filters. Control which fields are returned, how results are paginated and sorted, and optionally include property filters to find people connected to specific types of properties.

When property filters are included, set property_match to define the person-to-property relationship. Matching properties are nested in a properties array on each person.

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. You can mix people filters (source_type=people) and property filters (source_type=properties).

Filter object properties

body filter_idstringrequired

The filter slug from the List Filters endpoint (e.g., has_phone, estimated_value).

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. Omit or pass an empty array for the default set. Property fields appear in the nested properties array when property_match is set. Use person_coordinates to select both person_latitude and person_longitude, or coordinates to select both property coordinate values.

body property_matchstring

Required when property filters are present. Defines the person-to-property relationship. Ignored when only people filters are used.

Options: owner, resident, renter

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. Credits are consumed per entity.

When property_match is set and property filters are present, each person also includes a properties array with matching properties.

12345678910111213141516171819202122232425262728293031323334353637{
  "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 },
    { "number": "5125559999", "type": "landline", "do_not_call": false }
  ],
  "emails": [{ "address": "john.smith@example.com" }],
  "address": "456 Oak Lane",
  "city": "Austin",
  "state": "TX",
  "zip": "78701",
  "full_address": "456 Oak Lane, Austin, TX 78701",
  "properties": [
    {
      "dm_property_id": "prop_a1b2c3",
      "full_address": "1200 Barton Springs Rd, Austin, TX 78704",
      "address": "1200 Barton Springs Rd",
      "city": "Austin",
      "state": "TX",
      "zip": "78704",
      "latitude": 30.2598,
      "longitude": -97.7544,
      "images": {
        "street_view": "https://img.dealmachine.com/sv/30.2598,-97.7544.jpg",
        "satellite": "https://img.dealmachine.com/sat/30.2598,-97.7544.jpg",
        "roadmap": "https://img.dealmachine.com/map/30.2598,-97.7544.jpg"
      },
      "estimated_value": 875000,
      "estimated_equity_percentage": 72
    }
  ]
}

When no property filters are present, property_match is not needed and no properties array is included.

`properties`

The nested properties array on each person when property_match is set. Each property includes the always-included property fields plus any property fields you requested.

Field	Type	Description
`dm_property_id`	string	DealMachine internal property ID
`full_address`	string	Complete formatted address
`address`	string	Street address line
`city`	string	City
`state`	string	State abbreviation
`zip`	string	ZIP code
`latitude`	number	Property latitude
`longitude`	number	Property longitude
`images`	object	Signed URLs for `street_view`, `satellite`, and `roadmap`

`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 connected via `property_match`. `0` when no property filters are used.

`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

How Property Filters Work

When you include property filters in a people search:

The API finds properties matching the property filters.
It looks up people connected to those properties via the property_match relationship.
It applies any people filters to narrow down the results.
Matching properties are nested in a properties array on each person.

Property fields you request appear on each object in the properties array. Some base property fields (dm_property_id, address, city, state, zip) are always included.

If no property filters are present, property_match is not needed and no properties array is included in the response.

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.
property_match is required when any property filter is present, and ignored when only people filters are used.
When property_match is set, matching properties appear in a nested properties array on each person. Any property fields you request show up there.
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.

123456789101112131415curl -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" }
    ],
    "property_match": "owner",
    "filters": [
      { "filter_id": "estimated_value", "operator": "greater_than", "value": 500000 }
    ],
    "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

1234567891011121314151617181920212223242526272829303132curl -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" }
    ],
    "property_match": "owner",
    "filters": [
      {
        "filter_id": "estimated_value",
        "operator": "greater_than",
        "value": 500000
      },
      {
        "filter_id": "has_phone",
        "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

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647{
  "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 }],
      "emails": [{ "address": "john.smith@example.com" }],
      "address": "456 Oak Lane",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "full_address": "456 Oak Lane, Austin, TX 78701",
      "properties": [
        {
          "dm_property_id": "prop_a1b2c3",
          "full_address": "1200 Barton Springs Rd, Austin, TX 78704",
          "address": "1200 Barton Springs Rd",
          "city": "Austin",
          "state": "TX",
          "zip": "78704",
          "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
  }
}