Response Format

All search endpoints return results in a consistent envelope with three top-level keys: data, totals, and pagination.

Response Envelope

12345678910111213141516171819202122232425262728293031323334{
  "totals": {
    "properties": 1847,
    "people": 2134
  },
  "data": [
    {
      "dm_property_id": "prop_a1b2c3",
      "full_address": "1200 Barton Springs Rd, Austin, TX 78704",
      "address": "1200 Barton Springs Rd",
      "unit": null,
      "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": 575000,
      "estimated_equity_percentage": 72
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_results": 1847,
    "total_pages": 74,
    "has_next_page": true,
    "has_previous_page": false
  }
}

The `data` Array

The data array contains the matching records. Each record is a JSON object with always-included fields plus any fields you requested.

Always-included fields are present on every record regardless of your fields selection (see below).
Requested fields appear when you include their field_id in the fields array.
Default fields are returned if you omit the fields parameter or pass an empty array.
Values match the field type: numbers are JSON numbers, dates are YYYY-MM-DD strings, booleans are true/false, and multi-select values are arrays of option IDs.
Null values: Fields with no data return null.

The `totals` Object

Every search response includes a totals object with the full count of matching entities across the entire result set, regardless of pagination or anchor.

Field	Type	Description
`properties`	integer	Total number of matching properties
`people`	integer	Total number of matching people/contacts

These are the same values returned by the Count Properties and Count People endpoints — embedded directly in every search response so you don't need a separate call.

Always-Included Fields

These fields are present on every record in every response — you never need to request them.

Properties

Field	Type	Description
`dm_property_id`	string	DealMachine internal property ID
`full_address`	string	Complete formatted address (street, city, state, ZIP)
`address`	string	Street address line
`unit`	string \| null	Unit/apt number (e.g., "# 1", "Apt 203")
`city`	string	City
`state`	string	Two-letter state abbreviation
`zip`	string	5-digit ZIP code
`latitude`	number	Property latitude
`longitude`	number	Property longitude
`images`	object	Image URLs (see Images below)

People

When anchor is "people", each record in data represents a person. Person records always include:

Field	Type	Description
`dm_person_id`	string	DealMachine internal person ID
`full_name`	string	Full display name
`first_name`	string \| null	First/given name
`last_name`	string \| null	Last/family name
`phones`	array	Phone numbers (see Phones below)
`emails`	array	Email addresses (see Emails below)
`residence`	object	Where the person lives (see Residence below)
`property`	object	The associated property (see Nested Property below)

Residence

The residence object describes the person's primary address. It may differ from the property associated with the result. People search and enrichment retain their existing nullable address contract. Single and batch ID lookups, and contacts nested under property results, include this object when an address is available, including preview responses. Those lookups omit it when all address components are missing. Available objects use null for missing components; a missing ZIP is not returned as 00000.

Field	Type	Description
`address`	string \| null	Street address
`unit`	string \| null	Unit/apt (e.g., "APT 304", "UNIT 206")
`city`	string \| null	City
`state`	string \| null	Two-letter state abbreviation
`zip`	string \| null	5-digit ZIP code
`full_address`	string \| null	Complete formatted address

Nested Property

The property object contains the property associated with this person through the search — for example, a property they own, rent, or are otherwise connected to based on the contact_audience parameter. It uses the same structure as a property-anchored result, including images and any requested property fields like estimated_value.

Field	Type	Description
`dm_property_id`	string \| null	DealMachine property ID
`full_address`	string \| null	Complete formatted property address
`address`	string \| null	Property street address
`unit`	string \| null	Unit/apt number
`city`	string \| null	City
`state`	string \| null	State abbreviation
`zip`	string \| null	ZIP code
`latitude`	number \| null	Property latitude
`longitude`	number \| null	Property longitude
`images`	object \| null	Property image URLs

Images

Every property includes an images object with three views served via img.dealmachine.com. Image URLs are edge-cached and do not consume additional credits.

1234567{
  "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"
  }
}

Key	Description
`street_view`	Street-level photograph of the property
`satellite`	Aerial/bird's-eye satellite view
`roadmap`	Map view with streets and labels

Image URLs follow the pattern https://img.dealmachine.com/{type}/{lat},{lng}.jpg and support optional query parameters:

Parameter	Applies to	Default	Description
`size`	all	`500x500` (sv), `600x600` (sat/map)	Image dimensions (`WxH`)
`zoom`	sat, map	`19` (sat), `16` (map)	Google Maps zoom level
`heading`	sv	—	Camera heading in degrees (0–360)
`fov`	sv	`90`	Field of view in degrees
`pitch`	sv	`0`	Camera pitch in degrees

Image URLs are edge-cached and do not consume additional credits. If a street view is not available for a location, Google returns a grey placeholder tile — the CDN still caches and serves it.

Phones

The phones array on each person contains all available phone numbers:

12345678910111213141516{
  "phones": [
    {
      "number": "5125551234",
      "type": "wireless",
      "do_not_call": false,
      "carrier": "Verizon Wireless"
    },
    {
      "number": "5125559876",
      "type": "landline",
      "do_not_call": true,
      "carrier": null
    }
  ]
}

Field	Type	Description
`number`	string	10-digit phone number
`type`	string	`wireless`, `landline`, `voip`, `mobile` (a consumer mobile line confirmed by a second data source), or `unknown`
`do_not_call`	boolean	Whether the number is on the national Do Not Call registry
`carrier`	string \| null	Carrier name reported for the number (for example `Verizon Wireless`), or `null` when unknown

Phone objects have the same shape everywhere they appear: on a person from lookup, search, or enrichment, and on the contacts nested under a property.

Carrier

Always present. Every phone object has a carrier key. It is null when no carrier is on file for that number — never an empty string, and never omitted.
Free text, not a fixed list. The value is the carrier name exactly as the data provider reports it, such as Verizon Wireless, AT&T Mobility, or T-Mobile USA. Casing, punctuation, and legal-entity suffixes vary, and one network can appear under more than one name. Match on it case-insensitively or by substring rather than by exact equality.
Same value as the export. It is the same string the Phone Carrier column carries in a CSV export, so a number pulled both ways shows the same carrier. The one difference: an export's phone scrub options can blank a carrier along with the phone they remove, while the API applies no scrub.

Treat carrier as a routing hint, not a compliance record. It reflects the carrier on file when the number was last updated, so a number ported to another carrier can still show the original one, and a number on a reseller brand (an MVNO) may show either the brand or the network operator behind it. Do not use it on its own to make compliance decisions.

Emails

The emails array on each person contains all available email addresses:

1234567{
  "emails": [
    {
      "address": "john.smith@example.com"
    }
  ]
}

Field	Type	Description
`address`	string	Email address

The `credits` Object

Every endpoint that consumes credits includes a credits object in the response. This tells you exactly what was charged for the request.

12345678{
  "credits": {
    "used": 7,
    "properties": 5,
    "people": 2,
    "deduplicated": 3
  }
}

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)

The credits object is not included on non-billable endpoints (account info, filter metadata, field discovery) or when estimate_cost: true is used on search endpoints.

See Credits for full details on how credits work.

The `pagination` Object

Every response includes pagination metadata. See Pagination & Sorting for full details.

Field	Type	Description
`page`	integer	Current page number
`per_page`	integer	Results per page
`total_results`	integer	Total matching records
`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

Empty Results

When no records match your filters, the response still uses the same envelope:

123456789101112131415{
  "totals": {
    "properties": 0,
    "people": 0
  },
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_results": 0,
    "total_pages": 0,
    "has_next_page": false,
    "has_previous_page": false
  }
}

Error Responses

When a request fails, the API returns an error object instead of the data envelope. See Errors for the full error format and codes.

123456789101112131415{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "request_id": "req_abc123def456",
    "details": {
      "issues": [
        {
          "path": "filters[0].operator",
          "message": "Operator 'contains' is not allowed for NUMBER filter 'estimated_value'"
        }
      ]
    }
  }
}

Common search-related errors:

Status	Code	Cause
400	`validation_error`	Invalid filter, operator, value shape, or sort field
401	`invalid_api_key`	Missing or invalid API key
429	`rate_limit_exceeded`	Too many requests — back off and retry

Known litigators

People and nested contacts marked known_litigator: true retain their record and email addresses, but their phones array is empty. The flag is omitted for other people. The same phone scrubbing applies to exports and enrichment.

1234567{
  "dm_person_id": "per_12345",
  "full_name": "Example Person",
  "known_litigator": true,
  "phones": [],
  "emails": []
}

If the API cannot load its known-litigator lists, data requests return HTTP 503 with service_unavailable instead of returning unscreened contact data. Retry after the service recovers.