Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Response Format

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

Response Envelope

{ "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.
FieldTypeDescription
propertiesintegerTotal number of matching properties
peopleintegerTotal 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

FieldTypeDescription
dm_property_idstringDealMachine internal property ID
full_addressstringComplete formatted address (street, city, state, ZIP)
addressstringStreet address line
unitstring | nullUnit/apt number (e.g., "# 1", "Apt 203")
citystringCity
statestringTwo-letter state abbreviation
zipstring5-digit ZIP code
latitudenumberProperty latitude
longitudenumberProperty longitude
imagesobjectImage URLs (see Images below)
is_prospectbooleantrue when this property is one of your workspace's active or opportunity prospects
prospect_sourcestring | nullHow the prospect was first added (see Prospect fields below)
prospect_added_byobject | nullThe teammate who added the prospect
prospect_added_atstring | nullWhen the prospect was added (ISO 8601, UTC)

People

When anchor is "people", each record in data represents a person. Person records always include:
FieldTypeDescription
dm_person_idstringDealMachine internal person ID
full_namestringFull display name
first_namestring | nullFirst/given name
last_namestring | nullLast/family name
phonesarrayPhone numbers (see Phones below)
emailsarrayEmail addresses (see Emails below)
residenceobjectWhere the person lives (see Residence below)
is_prospectbooleantrue when this person is one of your workspace's active or opportunity prospects
prospect_sourcestring | nullHow the prospect was first added (see Prospect fields below)
prospect_added_byobject | nullThe teammate who added the prospect
prospect_added_atstring | nullWhen the prospect was added (ISO 8601, UTC)
propertyobjectThe 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.
FieldTypeDescription
addressstring | nullStreet address
unitstring | nullUnit/apt (e.g., "APT 304", "UNIT 206")
citystring | nullCity
statestring | nullTwo-letter state abbreviation
zipstring | null5-digit ZIP code
full_addressstring | nullComplete 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.
FieldTypeDescription
dm_property_idstring | nullDealMachine property ID
full_addressstring | nullComplete formatted property address
addressstring | nullProperty street address
unitstring | nullUnit/apt number
citystring | nullCity
statestring | nullState abbreviation
zipstring | nullZIP code
latitudenumber | nullProperty latitude
longitudenumber | nullProperty longitude
imagesobject | nullProperty image URLs

Prospect fields

Every top-level property and person record from Search Properties, Search People, and the single and batch ID lookups carries four prospect fields. They are always returned, including with enrich=false, and add no credits. They cannot be requested through fields and are not listed by List Fields.
{ "is_prospect": true, "prospect_source": "driving", "prospect_added_by": { "type": "user", "user_id": 7, "name": "Ana Ruiz", "api_key_id": null }, "prospect_added_at": "2026-10-20T15:04:05.000Z" }
FieldTypeDescription
is_prospectbooleantrue when the record is one of your workspace's active or opportunity prospects. Archived prospects read false.
prospect_sourcestring | nullHow the prospect was first added: direct, list, favorite, driving, import, opportunity, mail, api, zapier, cli, or mcp. driving means it was added while driving for dollars (D4D); every other source counts as Map on the Prospects page. null when is_prospect is false.
prospect_added_byobject | nullThe teammate who added the prospect, in the same shape as added_by on List Prospects: type, user_id, name, and api_key_id. null when is_prospect is false or no user is recorded.
prospect_added_atstring | nullWhen the prospect was added (ISO 8601, UTC). null when is_prospect is false.
  • Which prospect. Property records read the property's prospect. Person records read the person's prospect, including the people rows of Search Properties with anchor: "people".
  • Top-level records only. Contacts nested under a property, the property nested under a person, and properties nested under a person do not carry these fields. Batch lookup results with found: false do not carry them either.
  • To page through prospects by how and when they were added, use List Prospects with source_group, added_by, added_after, and added_before.

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.
{ "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" } }
KeyDescription
street_viewStreet-level photograph of the property
satelliteAerial/bird's-eye satellite view
roadmapMap view with streets and labels
Image URLs follow the pattern https://img.dealmachine.com/{type}/{lat},{lng}.jpg and support optional query parameters:
ParameterApplies toDefaultDescription
sizeall500x500 (sv), 600x600 (sat/map)Image dimensions (WxH)
zoomsat, map19 (sat), 16 (map)Google Maps zoom level
headingsv—Camera heading in degrees (0–360)
fovsv90Field of view in degrees
pitchsv0Camera 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:
{ "phones": [ { "number": "5125551234", "type": "wireless", "do_not_call": false, "carrier": "Verizon Wireless", "match_confidence": 99.6 }, { "number": "5125559876", "type": "landline", "do_not_call": true, "carrier": null, "match_confidence": null } ] }
FieldTypeDescription
numberstring10-digit phone number
typestringwireless, landline, voip, mobile (a consumer mobile line confirmed by a second data source), or unknown
do_not_callbooleanWhether the number is on the national Do Not Call registry
carrierstring | nullCarrier name reported for the number (for example Verizon Wireless), or null when unknown
match_confidencenumber | nullHow confident we are that this number belongs to the person, 0 to 100; null when unknown. See Match confidence
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:
{ "emails": [ { "address": "john.smith@example.com", "match_confidence": 87.5, "verification_status": "very_likely_deliverable" }, { "address": "jsmith@acme.com", "match_confidence": null, "verification_status": null, "type": "work", "company": "Acme" } ] }
FieldTypeDescription
addressstringEmail address
match_confidencenumber | nullHow confident we are that this address belongs to the person, 0 to 100; null when unknown. See Match confidence
verification_statusstring | nullWhether the address itself is deliverable; null when no verification is recorded. See Email verification status
typestringwork on an employer-sourced work email; omitted otherwise
companystringThe employer a work email came from, when known; omitted otherwise
Email objects have the same shape everywhere they appear, like phones.

Match confidence

match_confidence on each phone and email says how strongly that contact is associated with the person, so you can try the most likely number or address first.
  • Scale. A number from 0 to 100 with up to three decimals, such as 99.6 or 75.019. Higher means more confident. It is the same value the web app shows as "99.6% match".
  • Zero is a score. A score of 0 is returned as 0, never as null or left out.
  • null means unknown. The key is always present. null means no score is on file for that contact, which is different from a low score. Treat it as unknown, not as zero.
  • Not deliverability. Match confidence measures whether the contact belongs to this person. It says nothing about whether the number connects or the email is delivered. A number can be certainly this person's and still disconnected; an email can be valid and belong to someone else. Use verification_status for email deliverability.
  • Lines without a score. A phone or email added from a second data source beyond the person's own three phones and three emails has no score, so it returns null. When that second source confirms one of the person's own phones or emails instead, that entry keeps its score (and, for an email, its verification status) even though its type reads mobile or work.
The person-level flags has_deliverable_email and has_active_phone_number are unchanged. They describe the person as a whole; match_confidence and verification_status describe each contact.

Email verification status

verification_status on each email says whether the address itself is deliverable, from the most recent email verification. It is always one of these values, from least to most deliverable:
ValueMeaning
undeliverableMail to this address will not be delivered
deliverability_risk_lowDeliverability risk, low
deliverability_risk_mediumDeliverability risk, medium
likely_deliverable_lowLikely deliverable, lower confidence
likely_deliverable_highLikely deliverable, higher confidence
very_likely_deliverableVery likely deliverable
nullNo verification is recorded for this address (unknown)
Verification status measures whether the address works, not whether it belongs to this person; that is match_confidence. Do not use either one as a stand-in for the other.
Some records carry a verification result for the person's first email only. Their other emails return null until a verification is recorded.

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.
{ "credits": { "used": 7, "properties": 5, "people": 2, "deduplicated": 3 } }
FieldTypeDescription
usedintegerNew credits charged after deduplication
propertiesintegerProperty lead records evaluated in this response
peopleintegerPeople lead records evaluated in this response
deduplicatedintegerEntities 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.
FieldTypeDescription
pageintegerCurrent page number
per_pageintegerResults per page
total_resultsintegerTotal matching records
total_pagesintegerTotal pages available
has_next_pagebooleanWhether more pages exist after this one
has_previous_pagebooleanWhether pages exist before this one

Empty Results

When no records match your filters, the response still uses the same envelope:
{ "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.
{ "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:
StatusCodeCause
400validation_errorInvalid filter, operator, value shape, or sort field
401invalid_api_keyMissing or invalid API key
429rate_limit_exceededToo 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.
{ "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.

Phone usage

Every returned phone includes usage_2_months and usage_12_months. These describe the number's activity over the corresponding period, not the number of calls placed through DealMachine or how confidently the number matches the person.
Both fields are minimal, light, moderate, heavy, very_heavy, or no_data_or_no_usage. The last category combines no observed usage and no source data; it does not prove a number is inactive. A missing or unrecognized value is null. Usage is returned only with phone data you can already access, including enrichment and nested property contacts.
{ "number": "5125551234", "type": "wireless", "do_not_call": false, "carrier": "Verizon Wireless", "match_confidence": 99.6, "usage_2_months": "minimal", "usage_12_months": "heavy" }