Credits

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.

Before you pay

A free account can use property and people counts, field/filter discovery, and supported cost estimates without spending data credits. Counts do not award credits. Read workspace plans for live allowances and plan benefits, and usage for the current balance. Enrichment and record retrieval require paid access; other zero-credit operations can also require a subscription. Authentication, permissions and rate limits still apply.

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.

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

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, carrier), emails[] (with address)

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

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

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

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

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.

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

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

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.

Limited Contact Exports

For filter-based person, phone or email exports with a limit and chargeable property fields, property credits are scoped to the limited contact-row selection after deduplication and redaction. The API counts that property set before reserving credits. A person associated with several properties can require more property credits than the number of file rows. Billing-period deduplication still applies; credits.used reports new credits charged.

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

A property search can return more contacts than its initial credit estimate. In that case, the API keeps the credits already reserved and requests only the extra amount. If the available balance covers only part of the page, it returns the records that fit with a credit-limit warning. The credits object reports the final charge after deduplication.

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

123456789{
  "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)

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.

Credit Transparency in API Responses

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

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

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.

1234567891011121314151617181920212223// 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 and Search People.

To get just the total count of matching results (without cost estimates), use the count endpoints: Count Properties or Count People. Count endpoints are also free.

Checking Usage

Via CLI

1dm usage

Via API

12curl 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 for full details.

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.