Credit-efficient queries

DealMachine charges for the unique property and person records returned by a request. Filters define which records qualify. The response shape and requested output fields determine which entity types are billed.

This distinction lets you search properties for matching owners without automatically consuming a property credit for every match.

Start with the result you need

For POST /v1/properties/search, choose an anchor based on the entity you want as each result row:

Goal	Request configuration	Credit types
Return properties only	`anchor: "properties"`, `contact_audience: "none"`	Property
Return properties with contacts	`anchor: "properties"`, `contact_audience: "owners"` or another audience	Property and people
Return owners selected by property criteria	`anchor: "people"`, address/context fields only	People
Return owners with property intelligence	`anchor: "people"`, plus chargeable property fields	People and property

A property filter does not consume a property credit by itself. For example, filtering owners by estimated value and equity can still be people-only when those property values are not included in the response.

Return owners without property credits

Use a people anchor and request only the owner/contact data and property address context you need:

123456789101112131415161718curl -X POST "https://api.v2.dealmachine.com/v1/properties/search" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [{ "type": "zip_code", "code": "63101" }],
    "filters": [
      {
        "filter_id": "estimated_value",
        "operator": "range",
        "value": { "min": 200000, "max": 500000 }
      }
    ],
    "anchor": "people",
    "contact_audience": "owners",
    "fields": ["full_address"],
    "page": 1,
    "per_page": 25
  }'

Each result is a person with contact data, residence data, and nested property address context. The request consumes one people credit per unique returned person and no property credits.

The following property context does not add a property credit to a people-anchored search:

DealMachine property ID
Full and parsed address
Latitude and longitude
Property images

Other property output fields, including value, equity, building, mortgage, tax, sale, lien, and listing data, add a property credit for the associated property.

Owner names stored as property-record fields, such as owner_1_full_name, are property data. For person identity, phones, and emails billed as people data, use anchor: "people" and the returned person fields.

Avoid contacts when you only need properties

Property search defaults contact_audience to owners. Set it to none when you do not need contacts:

123456{
  "locations": [{ "type": "county", "code": "48201" }],
  "anchor": "properties",
  "contact_audience": "none",
  "fields": ["estimated_value"]
}

This request consumes property credits only. If you omit contact_audience, returned owners can add people credits.

The same property-only mode works for ID lookup and property enrichment:

1234567891011curl "https://api.v2.dealmachine.com/v1/properties/prop_12345?contact_audience=none&fields=estimated_value,year_built" \
  -H "Authorization: Bearer dm_sk_live_xxx"

curl -X POST "https://api.v2.dealmachine.com/v1/enrichment/address" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [{ "full_address": "1200 Barton Springs Rd, Austin, TX 78704" }],
    "fields": ["estimated_value", "year_built"],
    "contact_audience": "none"
  }'

Both requests return the selected property data, omit contacts, and consume zero people credits. fields controls the property output. contact_audience: "none" prevents owner or other contact records from being added. Use owners or another audience only when the application needs those people records.

Preview before retrieving data

Use this sequence for large searches:

Count matches
Call the corresponding count endpoint. Counts return no records and consume no credits.
Estimate the requested output
Send the search request with estimate_cost: true. The estimate reflects the selected anchor, contact audience, fields, page, and page size.
Retrieve a controlled page
Start with a page size that fits your budget, inspect the returned credits object, and then continue through additional pages.

Estimates are conservative. They do not calculate which entities your organization already accessed in the current billing period. Actual charges can be lower because of billing-period deduplication, licenses, or fewer contacts being returned than the maximum estimate.

Read the final credit summary

Billable responses include a credits object:

123456789{
  "credits": {
    "used": 18,
    "properties": 0,
    "people": 25,
    "deduplicated": 7,
    "licensed": 0
  }
}

used is the number of newly charged credits after deduplication and licensing.
properties and people show the returned entity counts evaluated for each credit type.
deduplicated shows billable entities that were already accessed during the billing period.
licensed shows records covered by an applicable data license.

Use credits.used as the final charge for the request. Do not treat the estimate as an invoice.

Apply the same rule to exports

Property exports also bill according to the selected output entities and fields. Person, phone, and email rows consume people credits. Property fields beyond address/context add property credits. Property-only rows consume property credits, while contacts included with property rows consume people credits.

Review the selected fields before starting a large export. Export reservations must fit within the available credit balance, so an export that requests both entity types can require substantially more credits than a people-only export.

Practical checklist

Use anchor: "people" when the desired rows are owners or contacts.
Use anchor: "properties" when the desired rows are properties.
Set contact_audience: "none" on property search, lookup, and enrichment when the result does not need contacts.
Filter on any fields needed to define the audience, but return only fields your application uses.
Keep people-anchored property output to address/context fields when you want people-only billing.
Count and estimate before retrieving a large result set.
Check the response's credits object after every billable request.
Expect the same unique property or person to be charged only once per billing period.

See Credits for the complete billing model and Fields for field discovery.