API Reference

The DealMachine API is organized around REST. All endpoints accept and return JSON.

Base URL

1https://api.v2.dealmachine.com/v1

Authentication

All protected endpoints require a Bearer token in the Authorization header:

12curl https://api.v2.dealmachine.com/v1/account \
  -H "Authorization: Bearer dm_sk_live_xxx"

Two token types are supported:

Token Type	Format	Access
API Key	`dm_sk_live_xxx`	Full access
OAuth Token	`dm_at_live_xxx`	Scoped access

Request Format

Content type: application/json
All timestamps are ISO 8601 format
IDs are integers or prefixed strings (e.g., key_abc123)

Response Format

Search endpoints return results in a data array alongside a pagination object:

12345678910111213141516171819202122232425262728293031323334353637383940{
  "data": [
    {
      "dm_property_id": "prop_a1b2c3",
      "full_address": "1200 Barton Springs Rd, Austin, TX 78704",
      "address": "1200 Barton Springs Rd",
      "city": "Austin",
      "state": "TX",
      "zip": "78704",
      "latitude": 30.2598,
      "longitude": -97.7544,
      "images": {
        "street_view": "https://img.dealmachine.com/sv/30.2598,-97.7544.jpg",
        "satellite": "https://img.dealmachine.com/sat/30.2598,-97.7544.jpg",
        "roadmap": "https://img.dealmachine.com/map/30.2598,-97.7544.jpg"
      },
      "estimated_value": 575000,
      "estimated_equity_percentage": 72,
      "num_bedrooms": 4,
      "contacts": [
        {
          "dm_person_id": "per_x1y2z3",
          "full_name": "John Smith",
          "phones": [
            { "number": "5125551234", "type": "wireless", "is_dnc": false }
          ],
          "match_status": "matched"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_results": 1847,
    "total_pages": 74,
    "has_next_page": true,
    "has_previous_page": false
  }
}

See Response Format for full details on always-included fields, field types, and pagination.

Error responses use a consistent structure:

123456789101112131415{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "request_id": "req_abc123def456",
    "details": {
      "issues": [
        {
          "path": "filters[0].operator",
          "message": "Operator 'contains' is not allowed for NUMBER filter 'estimated_value'"
        }
      ]
    }
  }
}

Response Headers

Header	Description
`X-Request-Id`	Unique request ID for debugging

Service health and source version

GET /health is an unauthenticated operational check at the API origin, outside the /v1 Endpoint catalog. It spends no credits and returns the running service's health and build identity:

123456{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-10-06T00:00:00.000Z",
  "sourceCommit": "0123456789abcdef0123456789abcdef01234567"
}

sourceCommit is the full Git commit embedded during the service build. Runtime settings cannot replace it. A local build without a deployment receipt returns null; older deployments may omit the field. When verifying a specific deployment, require the exact expected commit and reject a missing, null or different value. The response is not cached. A healthy process and matching source do not prove database readiness or successful authenticated operations.

Endpoint Groups

Group	Description
Authentication	Device authorization flow for CLI and MCP
OAuth	OAuth 2.0 authorization code flow
Account	Organization and user information
Filters	Discover available search filters
Fields	Discover available data fields
Properties	Search and count properties
People	Search and count people/contacts
Enrichment	Batch lookup by address, coordinates, APN, ID, email, phone, or name

Interactive Playground

Each endpoint page includes an interactive playground where you can test API calls directly in your browser. Enter your API key and try the endpoints in real time.