# DealMachine API

> Property intelligence platform for real estate investors. Search 160M+ US properties, enrich by address/coordinates/APN/email/phone/name, manage lists, run comps, send mail campaigns, and manage a CRM pipeline — all via REST API.

## Authentication

All endpoints (except signup and plans) require a Bearer token:

```
Authorization: Bearer dm_sk_live_xxx
```

API keys use the prefix `dm_sk_live_` (production) or `dm_sk_test_` (sandbox).

## Base URL

```
https://api.v2.dealmachine.com
```

All endpoints are prefixed with `/v1/`.

## Capabilities

- **Property Search**: Search 160M+ US properties by location (state, county, ZIP, radius, polygon, bounds) with 100+ filters. Count, paginate, sort, and export results.
- **People Search**: Search contacts associated with properties. Filter by demographics, contact info, and property attributes.
- **Enrichment**: Look up property/person records by address, lat/lng, APN, email, phone, or name. Property results cost property credits; returned contacts cost people credits; associated properties cost property credits. Misses are free.
- **Comparable Properties (Comps)**: Find comparable sales for a property by radius, timeframe, and criteria.
- **Locations**: Discover searchable locations (states, counties, ZIP codes) with metadata.
- **Filters & Fields**: Discover available search filters (types, operators, values) and data fields.
- **Lists**: Create, populate, build from filters, import IDs, and export saved lists.
- **Activity**: Track and search API usage history per organization.
- **Exports**: Export search results or lists as CSV with signed download URLs.
- **Account & Billing**: Sign up, browse plans, create checkout sessions, manage subscriptions, check credit usage.
- **CRM**: Manage pipelines, opportunities, labels, notes, tasks, records, and subscribers.
- **Mail**: Create postcard campaigns, manage designs, track wallet credits, set return addresses, and monitor delivery analytics.
- **OAuth**: Authorization code flow with PKCE for third-party integrations.
- **Device Auth**: RFC 8628 device authorization grant for CLI and headless apps.
- **Phones**: Check Do Not Call (DNC) registry status.
- **Addresses**: Validate and standardize addresses via USPS.

## Rate Limits

- 60 requests/minute, 5,000 requests/day per organization.
- Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Day-Limit`, `X-RateLimit-Day-Remaining`.

## Credits

Enrichment and search operations consume credits by entity type. Properties cost 1 property lead credit per unique property. Contacts/people cost 1 people lead credit per distinct person. Requests or exports that include both entity families charge both, based on the fields and contacts selected. Future company search should also bill per person. Re-accessing the same entity within a billing cycle is free (deduplication). Use `GET /v1/usage` to check remaining credits.

## Error Format

```json
{
  "error": {
    "code": "error_code",
    "message": "Human readable message",
    "request_id": "req_xxx",
    "details": {}
  }
}
```

## Links

- Full documentation: <https://api.docs.dealmachine.com/docs>
- OpenAPI spec: <https://api.docs.dealmachine.com/api-reference/openapi.json>
- Comprehensive LLM reference: <https://api.docs.dealmachine.com/llms-full.txt>
- CLI: `npm install -g @dealmachine/cli` (then `dm login`)
- MCP Server: `npm install -g @dealmachine/mcp` (works with Claude, ChatGPT, Cursor, VS Code Copilot, Windsurf, and every MCP-compatible client)