> ## Documentation Index
> Fetch the complete documentation index at: https://api.docs.dealmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit-efficient queries

> Choose fields, anchors, and contact audiences that match the records you need

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 |

<Note>
  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.
</Note>

## Return owners without property credits

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

```bash theme={null}
curl -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.

<Warning>
  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.
</Warning>

## Avoid contacts when you only need properties

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

```json theme={null}
{
  "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:

```bash theme={null}
curl "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:

<Steps>
  <Step title="Count matches">
    Call the corresponding count endpoint. Counts return no records and consume no credits.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Retrieve a controlled page">
    Start with a page size that fits your budget, inspect the returned `credits` object, and then
    continue through additional pages.
  </Step>
</Steps>

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:

```json theme={null}
{
  "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](/concepts/credits) for the complete billing model and [Fields](/concepts/fields) for
field discovery.