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

# Credits

> How API credits and usage billing works

The billing unit for data access through the DealMachine API and CLI. Each unique lead you retrieve with enrichment counts against your plan's monthly allowance.

## What's Included

All search, lookup, and batch endpoints return **enriched data** — base fields plus phones, emails, DNC status, and any requested `fields`. Credits are consumed by entity type: 1 credit per property and 1 credit per person/contact returned.

<Tip>
  Use `estimate_cost: true` on search endpoints to preview the credit cost of a request before
  committing to it. Count endpoints are also free.
</Tip>

### Common response fields

**Properties:** `dm_property_id`, `full_address`, `address`, `unit`, `city`, `state`, `zip`, `latitude`, `longitude`, `images`, `num_bedrooms`, `num_bathrooms`, `living_area_sqft`

**Contacts/People:** `dm_person_id`, `first_name`, `last_name`, `full_name`, `middle_initial`, `is_likely_owner`, `is_in_owner_family`, `is_resident`, `is_likely_renter`

### Enriched Fields

**Contacts:** `phones[]` (with `number`, `type`, `do_not_call`), `emails[]` (with `address`)

**Properties/People:** Any fields specified in the `fields` parameter (e.g., `estimated_value`, `year_built`, `equity_percent`, `person_age`, etc.)

<Note>
  "Common response fields" does not mean that every field is free in every response shape. In a
  people-anchored property search, property ID, address, coordinates, and images are credit-free
  context. Other property output fields add property credits. See [Credit-efficient
  queries](/concepts/credit-efficient-queries).
</Note>

## How Credits Work

| Entity                           | Cost     | Rule                                                                    |
| -------------------------------- | -------- | ----------------------------------------------------------------------- |
| **Property lead**                | 1 credit | Per unique property result                                              |
| **People lead**                  | 1 credit | Per unique person/contact result (same person with 3 phones = 1 credit) |
| **Returned property contacts**   | 1 credit | Per unique person/contact returned under a property                     |
| **Returned associated property** | 1 credit | Per unique property returned under a person/contact                     |

### What Counts

* **Find Properties / property lookup / property enrichment**: Costs 1 property data credit per unique property searched, looked up, or enriched. Contacts returned under those properties consume people credits.
* **Find People / person lookup / person enrichment**: Costs 1 people data credit per unique person/contact searched, looked up, or enriched, regardless of how many phone numbers or emails are returned. Properties returned with those people consume property credits.
* **Property filters used for a contact, phone, or email export**: Contact, phone, and email rows consume people credits. Chargeable property fields in the same export add property credits.
* **Future company search**: Company results will follow people billing semantics: 1 people data credit per person returned from the company search.

### What Doesn't Count

* Re-accessing the same property or contact within your billing month (already counted)
* Viewing your account info, filters, or field metadata
* Count endpoints and cost estimates

<Note>
  Credits are **deduplicated** within your billing period. If you access the same property or
  contact multiple times in one month, it only counts once.
</Note>

<Tip>
  Filters choose matching records but do not determine the billed entity type by themselves. Use a
  people anchor with address/context-only property output to return owners selected by property
  criteria without adding property credits. See [Credit-efficient
  queries](/concepts/credit-efficient-queries).
</Tip>

## Credit Rules by Endpoint

### Property Search (`POST /v1/properties/search`)

| `anchor`       | `contact_audience` | Property Credits                    | People Credits         |
| -------------- | ------------------ | ----------------------------------- | ---------------------- |
| `"properties"` | `"none"`           | 1 per property                      | 0                      |
| `"properties"` | `"owners"` etc.    | 1 per property                      | 1 per returned contact |
| `"people"`     | Required           | Depends on selected property fields | 1 per returned person  |

<Note>
  `contact_audience` defaults to `"owners"` on property search. Set it to `"none"` when you do not
  need contacts in the response.
</Note>

### People Search (`POST /v1/people/search`)

People search consumes one people credit per returned person. Property matching can narrow the
audience and provide associated address context, but it does not add property credits on this
endpoint.

### Single Lookups (`GET /v1/properties/:id`, `GET /v1/people/:id`)

* **Property lookup**: 1 property data credit; contacts requested with an audience other than `none` consume people credits. Use `contact_audience=none` for property-only data and zero people credits.
* **Person lookup**: 1 people data credit; properties requested with `include_properties=true` consume property credits

### Batch Lookups (`POST /v1/properties/ids`, `POST /v1/people/ids`)

Same credit rules as single lookups, applied per found entity.

## Monthly Allowance

Your plan and any additional credit balance determine the records available during a billing
period. Check [Get Credit Usage](/api-reference/account/get-usage) for `total_cap` and the live
`total_available` balance. Monthly credits reset at the start of each billing period. Purchased
additional credits remain in the additional-credit wallet until used.

## Credit limits

The API reserves credits before returning billable records. When the remaining balance cannot cover
the full request, supported search and batch endpoints can return a partial result with a warning.
Requests that cannot reserve any credits return a credit-limit error. Check usage and use smaller
pages to keep consumption predictable.

Every API response that costs credits includes a `credits` object so you always know what was charged:

```json theme={null}
{
  "data": [ ... ],
  "credits": {
    "used": 7,
    "properties": 5,
    "people": 2,
    "deduplicated": 3
  }
}
```

| Field          | Description                                          |
| -------------- | ---------------------------------------------------- |
| `used`         | New credits charged after deduplication              |
| `properties`   | Property lead records evaluated in this response     |
| `people`       | People lead records evaluated in this response       |
| `deduplicated` | Entities already accessed this billing period (free) |

<Tip>
  The `deduplicated` field tells you how many entities you already accessed this month — these are
  returned for free. Use this to understand your effective cost per request.
</Tip>

## Credit Transparency in API Responses

Every endpoint that returns billable data includes a `credits` object in the response.

<Note>
  Non-billable endpoints (account info, filter metadata, field discovery) do **not** include the
  `credits` object — only endpoints that access property or contact data.
</Note>

## Estimating Costs Before Searching

Use the `estimate_cost` parameter on search endpoints to preview the credit cost of a request **before committing to it**. A cost estimate validates your request and returns a page-aware cost estimate without returning data or consuming credits.

```json theme={null}
// POST /v1/properties/search  { "estimate_cost": true, "per_page": 25, "page": 1, "filters": [...] }
{
  "totals": {
    "properties": 1847,
    "people": 2134
  },
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_results": 1847,
    "total_pages": 74
  },
  "estimated_credits": {
    "this_page": 25,
    "total_all_pages": 1847,
    "breakdown": {
      "properties": 25,
      "people": 0,
      "already_accessed": 0,
      "note": "Estimate based on requested output. Actual credits may be lower due to returned contact counts, active licenses, and deduplication within your billing period."
    }
  }
}
```

* **`this_page`** — estimated credits for this page before deduplication and licensing
* **`total_all_pages`** — credits all pages combined would consume
* **`already_accessed`** — currently `0`; prior access is reflected in the final response instead

Cost estimate is available on both [Search Properties](/api-reference/properties/search-properties#cost-estimate) and [Search People](/api-reference/people/search-people#cost-estimate).

<Tip>
  To get just the **total count** of matching results (without cost estimates), use the count
  endpoints: [Count Properties](/api-reference/properties/count-properties) or [Count
  People](/api-reference/people/count-people). Count endpoints are also free.
</Tip>

## Checking Usage

### Via CLI

```bash theme={null}
dm usage
```

### Via API

```bash theme={null}
curl https://api.v2.dealmachine.com/v1/usage \
  -H "Authorization: Bearer dm_sk_live_xxx"
```

Returns your plan, billing cycle dates, total credits used/remaining, and a per-entity breakdown. See [Get Credit Usage](/api-reference/account/get-usage) for full details.

<Note>
  API, CLI, and DealMachine product access use the same organization billing period and entity-level
  deduplication rules. They also share the same Redis reservation counter and reconcile it with the
  durable credit ledger before reporting a live balance.
</Note>