Search People - DealMachine API

curl -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",
      "equity_percent"
    ],
    "page": 1,
    "per_page": 25,
    "sort": [
      { "field_id": "full_name", "direction": "asc" }
    ]
  }'

{
  "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,
          "equity_percent": 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
  }
}

POST

people

curl -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",
      "equity_percent"
    ],
    "page": 1,
    "per_page": 25,
    "sort": [
      { "field_id": "full_name", "direction": "asc" }
    ]
  }'

{
  "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,
          "equity_percent": 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
  }
}

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.

Body Parameters

locations

array

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.

Show Location object properties

type

string

required

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

code

string

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

latitude

number

Center point latitude. Required for radius.

longitude

number

Center point longitude. Required for radius.

radius_miles

number

Search radius in miles. Required for radius.

coordinates

array

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

filters

array

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).

Show Filter object properties

filter_id

string

required

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

operator

string

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

value

any

required

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

include_lists

object

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

exclude_lists

object

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

exclude_previously_exported

boolean | object

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

bigquery_data_environment

integer

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

fields

string[]

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.

property_match

string

Required when property filters are present. Defines the person-to-property relationship. Ignored when only people filters are used.Options: owner, resident, renter

page

integer

default:1

Page number (min: 1).

per_page

integer

default:25

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

sort

array

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

Show Sort object properties

field_id

string

required

The field to sort by.

direction

string

required

asc (ascending) or desc (descending).

estimate_cost

boolean

default:false

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

curl -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",
      "equity_percent"
    ],
    "page": 1,
    "per_page": 25,
    "sort": [
      { "field_id": "full_name", "direction": "asc" }
    ]
  }'

{
  "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,
          "equity_percent": 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
  }
}

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.

{
  "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,
      "equity_percent": 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.

{
  "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.

{
  "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 filter is required. Passing an empty filters array returns a validation error.
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.

curl -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:

{
  "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": 47,
    "total_all_pages": 799,
    "breakdown": {
      "people": 25,
      "properties": 22,
      "already_accessed": 6,
      "note": "6 entities on this page were already accessed this billing period (no charge)"
    }
  }
}

Field	Type	Description
`estimated_credits.this_page`	integer	Credits this page would consume (new entities only)
`estimated_credits.total_all_pages`	integer	Credits all pages combined would consume
`estimated_credits.breakdown.people`	integer	People enrichment credits on this page
`estimated_credits.breakdown.properties`	integer	Property enrichment credits on this page (only when `property_match` is set)
`estimated_credits.breakdown.already_accessed`	integer	Entities already accessed this billing period (free)

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.

Get People by IDs Count People

⌘I

​Body Parameters

​Response

​data

​properties

​totals

​credits

​pagination

​How Property Filters Work

​Notes

​Cost Estimate

Body Parameters

Response

`data`

`properties`

`totals`

`credits`

`pagination`

How Property Filters Work

Notes

Cost Estimate