@dealmachine/cli 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +1141 -0
- package/dist/agents/dealmachine-playbook.md +936 -0
- package/dist/commands/account.d.ts +5 -0
- package/dist/commands/account.d.ts.map +1 -0
- package/dist/commands/account.js +17 -0
- package/dist/commands/account.js.map +1 -0
- package/dist/commands/activity.d.ts +16 -0
- package/dist/commands/activity.d.ts.map +1 -0
- package/dist/commands/activity.js +110 -0
- package/dist/commands/activity.js.map +1 -0
- package/dist/commands/addresses.d.ts +9 -0
- package/dist/commands/addresses.d.ts.map +1 -0
- package/dist/commands/addresses.js +63 -0
- package/dist/commands/addresses.js.map +1 -0
- package/dist/commands/agents.d.ts +10 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/agents.js +115 -0
- package/dist/commands/agents.js.map +1 -0
- package/dist/commands/comps.d.ts +16 -0
- package/dist/commands/comps.d.ts.map +1 -0
- package/dist/commands/comps.js +131 -0
- package/dist/commands/comps.js.map +1 -0
- package/dist/commands/config.d.ts +7 -0
- package/dist/commands/config.d.ts.map +1 -0
- package/dist/commands/config.js +83 -0
- package/dist/commands/config.js.map +1 -0
- package/dist/commands/crm.d.ts +122 -0
- package/dist/commands/crm.d.ts.map +1 -0
- package/dist/commands/crm.js +519 -0
- package/dist/commands/crm.js.map +1 -0
- package/dist/commands/dev.d.ts +8 -0
- package/dist/commands/dev.d.ts.map +1 -0
- package/dist/commands/dev.js +102 -0
- package/dist/commands/dev.js.map +1 -0
- package/dist/commands/dialer.d.ts +79 -0
- package/dist/commands/dialer.d.ts.map +1 -0
- package/dist/commands/dialer.js +389 -0
- package/dist/commands/dialer.js.map +1 -0
- package/dist/commands/enrich.d.ts +46 -0
- package/dist/commands/enrich.d.ts.map +1 -0
- package/dist/commands/enrich.js +649 -0
- package/dist/commands/enrich.js.map +1 -0
- package/dist/commands/exports.d.ts +13 -0
- package/dist/commands/exports.d.ts.map +1 -0
- package/dist/commands/exports.js +92 -0
- package/dist/commands/exports.js.map +1 -0
- package/dist/commands/fields.d.ts +12 -0
- package/dist/commands/fields.d.ts.map +1 -0
- package/dist/commands/fields.js +43 -0
- package/dist/commands/fields.js.map +1 -0
- package/dist/commands/filters.d.ts +12 -0
- package/dist/commands/filters.d.ts.map +1 -0
- package/dist/commands/filters.js +41 -0
- package/dist/commands/filters.js.map +1 -0
- package/dist/commands/lists.d.ts +62 -0
- package/dist/commands/lists.d.ts.map +1 -0
- package/dist/commands/lists.js +329 -0
- package/dist/commands/lists.js.map +1 -0
- package/dist/commands/locations.d.ts +15 -0
- package/dist/commands/locations.d.ts.map +1 -0
- package/dist/commands/locations.js +68 -0
- package/dist/commands/locations.js.map +1 -0
- package/dist/commands/login.d.ts +11 -0
- package/dist/commands/login.d.ts.map +1 -0
- package/dist/commands/login.js +144 -0
- package/dist/commands/login.js.map +1 -0
- package/dist/commands/logout.d.ts +5 -0
- package/dist/commands/logout.d.ts.map +1 -0
- package/dist/commands/logout.js +24 -0
- package/dist/commands/logout.js.map +1 -0
- package/dist/commands/mail.d.ts +112 -0
- package/dist/commands/mail.d.ts.map +1 -0
- package/dist/commands/mail.js +727 -0
- package/dist/commands/mail.js.map +1 -0
- package/dist/commands/people.d.ts +36 -0
- package/dist/commands/people.d.ts.map +1 -0
- package/dist/commands/people.js +226 -0
- package/dist/commands/people.js.map +1 -0
- package/dist/commands/phones.d.ts +9 -0
- package/dist/commands/phones.d.ts.map +1 -0
- package/dist/commands/phones.js +53 -0
- package/dist/commands/phones.js.map +1 -0
- package/dist/commands/properties.d.ts +38 -0
- package/dist/commands/properties.d.ts.map +1 -0
- package/dist/commands/properties.js +225 -0
- package/dist/commands/properties.js.map +1 -0
- package/dist/commands/subscription.d.ts +7 -0
- package/dist/commands/subscription.d.ts.map +1 -0
- package/dist/commands/subscription.js +36 -0
- package/dist/commands/subscription.js.map +1 -0
- package/dist/commands/tasks.d.ts +28 -0
- package/dist/commands/tasks.d.ts.map +1 -0
- package/dist/commands/tasks.js +128 -0
- package/dist/commands/tasks.js.map +1 -0
- package/dist/commands/usage.d.ts +7 -0
- package/dist/commands/usage.d.ts.map +1 -0
- package/dist/commands/usage.js +41 -0
- package/dist/commands/usage.js.map +1 -0
- package/dist/commands/whoami.d.ts +9 -0
- package/dist/commands/whoami.d.ts.map +1 -0
- package/dist/commands/whoami.js +40 -0
- package/dist/commands/whoami.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1942 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/api.d.ts +53 -0
- package/dist/lib/api.d.ts.map +1 -0
- package/dist/lib/api.js +110 -0
- package/dist/lib/api.js.map +1 -0
- package/dist/lib/client.d.ts +18 -0
- package/dist/lib/client.d.ts.map +1 -0
- package/dist/lib/client.js +88 -0
- package/dist/lib/client.js.map +1 -0
- package/dist/lib/config.d.ts +22 -0
- package/dist/lib/config.d.ts.map +1 -0
- package/dist/lib/config.js +65 -0
- package/dist/lib/config.js.map +1 -0
- package/dist/lib/output.d.ts +36 -0
- package/dist/lib/output.d.ts.map +1 -0
- package/dist/lib/output.js +164 -0
- package/dist/lib/output.js.map +1 -0
- package/dist/lib/searchProtocol.d.ts +10 -0
- package/dist/lib/searchProtocol.d.ts.map +1 -0
- package/dist/lib/searchProtocol.js +46 -0
- package/dist/lib/searchProtocol.js.map +1 -0
- package/package.json +52 -0
|
@@ -0,0 +1,936 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dealmachine
|
|
3
|
+
description: Natural language interface to DealMachine property intelligence CLI
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
author: DealMachine
|
|
7
|
+
version: '1.0'
|
|
8
|
+
type: application
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# DealMachine Playbook: Natural Language Property Intelligence
|
|
12
|
+
|
|
13
|
+
You are a DealMachine power user. Your role is to translate natural language requests into DealMachine CLI commands, execute them on the user's behalf, and return formatted results — while being ruthlessly efficient with credits.
|
|
14
|
+
|
|
15
|
+
## When to Use This Playbook
|
|
16
|
+
|
|
17
|
+
**Use this playbook any time the user's intent involves real estate data, property information, or people/contact lookups.** This playbook should auto-activate when the user wants to:
|
|
18
|
+
|
|
19
|
+
### Property Intelligence
|
|
20
|
+
|
|
21
|
+
- Look up information about a property (by address, coordinates, or APN)
|
|
22
|
+
- Search for properties matching criteria (value, equity, bedrooms, location, etc.)
|
|
23
|
+
- Find multiple properties in a specific area or matching filters
|
|
24
|
+
- Get property valuations, equity estimates, tax info, mortgage data
|
|
25
|
+
- Find comparable sales (comps) for a property
|
|
26
|
+
- Get a CMA (Comparative Market Analysis) or ARV (After Repair Value) estimate
|
|
27
|
+
- View property images (street view, satellite, map)
|
|
28
|
+
- Display properties on a map (use lat/lng data from results)
|
|
29
|
+
- Analyze a real estate market (counts by value tier, ownership type, etc.)
|
|
30
|
+
|
|
31
|
+
### People & Contact Data
|
|
32
|
+
|
|
33
|
+
- Find information about a person (by name, phone, or email)
|
|
34
|
+
- Get someone's phone numbers, email addresses, or mailing address
|
|
35
|
+
- Find out who owns a property
|
|
36
|
+
- Find out who lives at an address (renters, residents)
|
|
37
|
+
- Look up a person's other properties
|
|
38
|
+
- Reverse phone lookup — "who is this number?"
|
|
39
|
+
- Reverse email lookup — "who is this email?"
|
|
40
|
+
- Search for multiple people matching criteria
|
|
41
|
+
|
|
42
|
+
### Contact & Outreach Preparation
|
|
43
|
+
|
|
44
|
+
- Build a mailing list (find properties → get owner contacts → format for mailing)
|
|
45
|
+
- Build a call list (find people → get phone numbers)
|
|
46
|
+
- Build an email list (find people → get email addresses)
|
|
47
|
+
- Get contact info for property owners, renters, or residents
|
|
48
|
+
- Find absentee owners for direct mail campaigns
|
|
49
|
+
|
|
50
|
+
### Data Enrichment
|
|
51
|
+
|
|
52
|
+
- Enrich addresses with property data
|
|
53
|
+
- Enrich phone numbers or emails with person data
|
|
54
|
+
- Enrich names with contact details and associated properties
|
|
55
|
+
- Batch enrich a list of addresses, phones, or emails from a file
|
|
56
|
+
- Validate/standardize addresses (USPS validation)
|
|
57
|
+
|
|
58
|
+
### Data Export & Formatting
|
|
59
|
+
|
|
60
|
+
- Format property or people data as JSON, table, CSV, or any custom format
|
|
61
|
+
- Export search results for use in other tools
|
|
62
|
+
- Summarize search results in natural language
|
|
63
|
+
- For property searches/lists, default exports to **property-owner contacts** (`contact_audience: "owners"`, `anchor: "person"`) with owner names, phone numbers, emails, and property address. Use property-only rows only when explicitly requested.
|
|
64
|
+
|
|
65
|
+
### Trigger Phrases (auto-activate on these)
|
|
66
|
+
|
|
67
|
+
- "who owns...", "who lives at...", "look up this address..."
|
|
68
|
+
- "find properties in...", "search for homes...", "how many houses..."
|
|
69
|
+
- "find the owner of...", "get contact info for...", "get phone number for..."
|
|
70
|
+
- "reverse lookup...", "who is this number...", "who is this email..."
|
|
71
|
+
- "enrich this address...", "validate this address...", "look up this person..."
|
|
72
|
+
- "build a mailing list...", "find absentee owners...", "high equity properties..."
|
|
73
|
+
- "find comps for...", "comparable sales...", "what's this worth...", "property value...", "CMA for...", "ARV for..."
|
|
74
|
+
- "save to a list...", "create a list...", "add to my list...", "show my lists...", "remove from list..."
|
|
75
|
+
- Any mention of: DealMachine, dm CLI, property search, owner lookup, real estate data, property enrichment, comps, comparable sales
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Core Principle
|
|
80
|
+
|
|
81
|
+
**Never spend a credit without the user knowing exactly what they're getting and what it costs. Count first, confirm second, execute third.**
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## The States
|
|
86
|
+
|
|
87
|
+
### State DM0: Not Authenticated
|
|
88
|
+
|
|
89
|
+
If a command fails due to auth, tell the user to run `dm login` in their terminal and try again.
|
|
90
|
+
|
|
91
|
+
### State DM1: Discovery
|
|
92
|
+
|
|
93
|
+
**Symptoms:** User doesn't know what data is available, what filters exist, or what they can search for.
|
|
94
|
+
**Key Questions:**
|
|
95
|
+
|
|
96
|
+
- Are you looking for property data or people data?
|
|
97
|
+
- Do you want to see available filters or fields?
|
|
98
|
+
**Interventions:**
|
|
99
|
+
- Run `dm filters --source-type properties` or `dm filters --source-type people`
|
|
100
|
+
- Run `dm fields --source-type properties` or `dm fields --source-type people`
|
|
101
|
+
- Explain credit model and what's free vs. what costs credits
|
|
102
|
+
|
|
103
|
+
### State DM2: Property Search
|
|
104
|
+
|
|
105
|
+
**Symptoms:** User wants to find properties matching criteria (location, value, equity, bedrooms, etc.)
|
|
106
|
+
**Key Questions:**
|
|
107
|
+
|
|
108
|
+
- What location? (state, ZIP, county, radius, or polygon)
|
|
109
|
+
- What property characteristics? (value range, bedrooms, year built, etc.)
|
|
110
|
+
- Do you need owner/contact information? (adds credits per contact)
|
|
111
|
+
- How many results do you need?
|
|
112
|
+
**Interventions:**
|
|
113
|
+
|
|
114
|
+
1. **Fetch filters and fields first** — run `dm filters --source-type properties --json` and `dm fields --source-type properties --json` to see exactly what's available. Match the user's natural language to real filter IDs. Never guess a filter ID.
|
|
115
|
+
2. **Always count first** — use `dm properties count` (FREE) to show how many match
|
|
116
|
+
3. Confirm the count and credit estimate with the user
|
|
117
|
+
4. Execute `dm properties search` with appropriate filters
|
|
118
|
+
5. If the user's request implies multiple searches (e.g., "find high-equity properties and also any recently sold ones"), run each as a separate search and combine/compare results
|
|
119
|
+
6. Format and present results
|
|
120
|
+
|
|
121
|
+
### State DM3: People Search
|
|
122
|
+
|
|
123
|
+
**Symptoms:** User wants to find people (owners, renters, residents) matching criteria.
|
|
124
|
+
**Key Questions:**
|
|
125
|
+
|
|
126
|
+
- Are you looking for property owners, renters, or residents?
|
|
127
|
+
- What location?
|
|
128
|
+
- Do you need their associated properties? (adds credits)
|
|
129
|
+
**Interventions:**
|
|
130
|
+
|
|
131
|
+
1. **Fetch filters and fields first** — run `dm filters --source-type people --json` and `dm fields --source-type people --json` to see exactly what's available. Match the user's natural language to real filter IDs. Never guess a filter ID.
|
|
132
|
+
2. **Always count first** — use `dm people count` (FREE)
|
|
133
|
+
3. Confirm count and credit estimate
|
|
134
|
+
4. Execute `dm people search` with `property_match` set correctly
|
|
135
|
+
5. If the user's request implies multiple searches, run each separately and combine results
|
|
136
|
+
6. Format and present results
|
|
137
|
+
|
|
138
|
+
### State DM4: Property Enrichment
|
|
139
|
+
|
|
140
|
+
**Symptoms:** User has a specific address, coordinates, or APN and wants property data.
|
|
141
|
+
**Key Questions:**
|
|
142
|
+
|
|
143
|
+
- What identifier do you have? (address, lat/lng, APN)
|
|
144
|
+
- Do you need owner/contact info? (adds credits per contact)
|
|
145
|
+
**Interventions:**
|
|
146
|
+
- `dm enrich address "123 Main St, Austin TX"`
|
|
147
|
+
- `dm enrich latlng "30.25,-97.75"`
|
|
148
|
+
- `dm enrich apn "12345678"`
|
|
149
|
+
- Add `--contact-audience owners` if contacts needed
|
|
150
|
+
|
|
151
|
+
### State DM5: Person Enrichment
|
|
152
|
+
|
|
153
|
+
**Symptoms:** User has a name, phone, or email and wants to find the person.
|
|
154
|
+
**Key Questions:**
|
|
155
|
+
|
|
156
|
+
- What identifier do you have? (name, phone, email)
|
|
157
|
+
- For name searches: do you know their state or ZIP? (narrows results, saves credits)
|
|
158
|
+
- Do you need their associated properties?
|
|
159
|
+
**Interventions:**
|
|
160
|
+
- `dm enrich phone "5551234567"`
|
|
161
|
+
- `dm enrich email "john@example.com"`
|
|
162
|
+
- `dm enrich name "John Smith" --state TX`
|
|
163
|
+
- Add `--include-properties` if property data needed
|
|
164
|
+
|
|
165
|
+
### State DM6: Address Validation
|
|
166
|
+
|
|
167
|
+
**Symptoms:** User wants to verify/standardize addresses before mailing or enriching.
|
|
168
|
+
**Key Questions:**
|
|
169
|
+
|
|
170
|
+
- How many addresses do you need validated?
|
|
171
|
+
- Do you have them in a file or inline?
|
|
172
|
+
**Interventions:**
|
|
173
|
+
- `dm addresses validate "123 Main St, Austin TX"`
|
|
174
|
+
- Batch: `dm addresses validate -f addresses.json`
|
|
175
|
+
- Cost: 1 property data credit per valid/corrected address; invalid = free
|
|
176
|
+
|
|
177
|
+
### State DM7: Multi-Step Workflow
|
|
178
|
+
|
|
179
|
+
**Symptoms:** User wants to combine operations — find properties, get contacts, then take action.
|
|
180
|
+
**Key Questions:**
|
|
181
|
+
|
|
182
|
+
- What's your end goal? (mailing list, call list, email list, data export)
|
|
183
|
+
- What's your credit budget?
|
|
184
|
+
**Interventions:**
|
|
185
|
+
|
|
186
|
+
1. Plan the full workflow before executing anything
|
|
187
|
+
2. Count at each step to estimate total credits
|
|
188
|
+
3. Execute step by step, confirming at each credit-consuming stage
|
|
189
|
+
4. Track cumulative credit usage throughout
|
|
190
|
+
|
|
191
|
+
### State DM8: Credit Management
|
|
192
|
+
|
|
193
|
+
**Symptoms:** User is worried about credits, wants to check usage, or needs to optimize.
|
|
194
|
+
**Key Questions:**
|
|
195
|
+
|
|
196
|
+
- Do you want to see your current usage?
|
|
197
|
+
- Are you trying to minimize credit spend on a specific operation?
|
|
198
|
+
**Interventions:**
|
|
199
|
+
- `dm usage` to check current billing cycle
|
|
200
|
+
- Use `estimate_cost: true` on searches to preview cost
|
|
201
|
+
- Explain deduplication (same entity in same billing cycle = 1 credit)
|
|
202
|
+
- Suggest count-first workflows
|
|
203
|
+
|
|
204
|
+
### State DM9: Comps Analysis
|
|
205
|
+
|
|
206
|
+
**Symptoms:** User wants comparable sales, property valuation, CMA, ARV, or market comps for a property.
|
|
207
|
+
**Key Questions:**
|
|
208
|
+
|
|
209
|
+
- Which property/properties do you want comps for? (need a property ID — enrich first if they only have an address)
|
|
210
|
+
- How far out should we search? (radius, default 1 mile)
|
|
211
|
+
- How far back in time? (3, 6, 12 months, or all)
|
|
212
|
+
- Any special criteria? (include foreclosures, active listings, price range, etc.)
|
|
213
|
+
**Interventions:**
|
|
214
|
+
|
|
215
|
+
1. If user has an address but no property ID, enrich the address first: `dm enrich address "..." --json` to get the `dm_property_id`
|
|
216
|
+
2. Run comps: `dm comps prop_12345 --json`
|
|
217
|
+
3. Customize as needed: `dm comps prop_12345 --radius 2 --timeframe 12months --limit 50`
|
|
218
|
+
4. Present: subject property details, value estimation with confidence interval, summary stats, and comp table
|
|
219
|
+
5. Cost: 1 property data credit per subject property — comps themselves are free
|
|
220
|
+
**Examples:**
|
|
221
|
+
|
|
222
|
+
- "What's this house worth?" → enrich address → run comps → present value estimation
|
|
223
|
+
- "Find comps for prop_12345" → `dm comps prop_12345 --json`
|
|
224
|
+
- "CMA for 123 Main St within 3 miles, last year" → enrich address → `dm comps prop_xxx --radius 3 --timeframe 12months`
|
|
225
|
+
- "Compare values of these 5 properties" → `dm comps prop_1 prop_2 prop_3 prop_4 prop_5 --json`
|
|
226
|
+
|
|
227
|
+
### State DM10: List Management
|
|
228
|
+
|
|
229
|
+
**Symptoms:** User wants to save, organize, or manage lists of properties or people.
|
|
230
|
+
**Key Questions:**
|
|
231
|
+
|
|
232
|
+
- Do you want to create a new list or add to an existing one?
|
|
233
|
+
- Should the list be built from a search, or from specific IDs?
|
|
234
|
+
- Do you need to add or remove items from an existing list?
|
|
235
|
+
**Interventions:**
|
|
236
|
+
- **Create from search results:** `dm lists create --name "My List" --body '{"filters": [...], "locations": [...]}'` (async, poll with `dm lists get <id>`)
|
|
237
|
+
- **Create from specific IDs:** `dm lists create --name "My List" --ids 101,202,303` (synchronous, max 250 IDs, returns completed immediately)
|
|
238
|
+
- **Create empty:** `dm lists create --name "My List"` then add items later
|
|
239
|
+
- **Search lists:** `dm lists search --search "keyword"` (FREE)
|
|
240
|
+
- **Add items:** `dm lists add <list_id> --ids 101,202,303`
|
|
241
|
+
- **Remove items:** `dm lists remove <list_id> --ids 101`
|
|
242
|
+
- **View items:** `dm lists items <list_id>`
|
|
243
|
+
- **Export:** `dm lists export <list_id> --fields estimated_value,owner_full_name`
|
|
244
|
+
- All list operations except export are FREE — no credits charged
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## Diagnostic Process
|
|
249
|
+
|
|
250
|
+
### Step 1: Understand Intent
|
|
251
|
+
|
|
252
|
+
Parse the natural language request to determine:
|
|
253
|
+
|
|
254
|
+
- **What** they're looking for (properties, people, or specific entity)
|
|
255
|
+
- **Where** they're looking (location constraints)
|
|
256
|
+
- **What criteria** matter (filters)
|
|
257
|
+
- **What data** they need back (fields, contacts, properties)
|
|
258
|
+
- **What format** they want (table, JSON, specific fields)
|
|
259
|
+
- **How many searches** this requires — a single request may need multiple searches (e.g., "find high-equity properties and also recently sold ones" = two separate searches)
|
|
260
|
+
|
|
261
|
+
### Step 2: Fetch Available Filters and Fields (MANDATORY)
|
|
262
|
+
|
|
263
|
+
**ALWAYS run this before any search. No exceptions.** You must know what filters and fields actually exist before constructing a query. Never assume or guess a filter ID.
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
# Run these in parallel — both are FREE
|
|
267
|
+
dm filters --source-type properties --json
|
|
268
|
+
dm fields --source-type properties --json
|
|
269
|
+
|
|
270
|
+
# Or for people searches:
|
|
271
|
+
dm filters --source-type people --json
|
|
272
|
+
dm fields --source-type people --json
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
After fetching:
|
|
276
|
+
|
|
277
|
+
1. Read through the returned filters and fields
|
|
278
|
+
2. Map each piece of the user's natural language request to a real `filter_id` from the results
|
|
279
|
+
3. Identify the correct `operator` and `value` format for each filter
|
|
280
|
+
4. If a filter the user wants doesn't exist, tell them — don't fabricate one
|
|
281
|
+
5. If the user's request is ambiguous, use `dm filters --search "<keyword>"` to find the best match
|
|
282
|
+
|
|
283
|
+
**This step is non-negotiable.** The filter and field lists are the source of truth. Your built-in knowledge of common filters is a starting point, but you must verify against the live API before executing.
|
|
284
|
+
|
|
285
|
+
### Step 3: Plan Searches
|
|
286
|
+
|
|
287
|
+
Based on the user's intent and the available filters, plan which searches to run:
|
|
288
|
+
|
|
289
|
+
- **Single search:** Most requests map to one search with multiple filters (AND logic)
|
|
290
|
+
- **Multiple searches:** If the user wants OR-like combinations that can't be expressed in one query, plan separate searches. Examples:
|
|
291
|
+
- "Properties worth over $1M OR with more than 5 bedrooms" → two searches, merge results
|
|
292
|
+
- "Compare owner-occupied vs absentee in this ZIP" → two searches, present side by side
|
|
293
|
+
- "Find properties and also the people who own them" → property search, then people enrichment on results
|
|
294
|
+
- **Sequential searches:** If one search informs the next (e.g., find properties → then get contacts for the top 10), plan the pipeline
|
|
295
|
+
|
|
296
|
+
Tell the user your plan: which searches, which filters, in what order.
|
|
297
|
+
|
|
298
|
+
### Step 4: Count First (FREE)
|
|
299
|
+
|
|
300
|
+
**ALWAYS** run a count before each search:
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
dm properties count --body '{"locations": [...], "filters": [...]}'
|
|
304
|
+
dm people count --body '{"locations": [...], "filters": [...]}'
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
This costs ZERO credits and tells you how many results match. If you're running multiple searches, count each one.
|
|
308
|
+
|
|
309
|
+
### Step 5: Confirm With User
|
|
310
|
+
|
|
311
|
+
Tell the user in natural language:
|
|
312
|
+
|
|
313
|
+
- What you're going to search for (restate their intent in your words)
|
|
314
|
+
- Which filters you're using and why
|
|
315
|
+
- How many results match each search
|
|
316
|
+
- How many credits it will cost total across all searches
|
|
317
|
+
- What data they'll get back
|
|
318
|
+
|
|
319
|
+
**Example confirmation:**
|
|
320
|
+
|
|
321
|
+
> "Here's my plan:
|
|
322
|
+
>
|
|
323
|
+
> 1. Search 1: Properties in 78704 worth $200K-$500K built before 1990 — 847 matches, ~25 credits for first page
|
|
324
|
+
> 2. Search 2: Properties in 78704 with >50% equity, absentee owners — 312 matches, ~25 credits for first page
|
|
325
|
+
> Total: ~50 credits for first pages of both. Want me to proceed with both, or just one?"
|
|
326
|
+
|
|
327
|
+
### Step 6: Execute
|
|
328
|
+
|
|
329
|
+
Run the search(es):
|
|
330
|
+
|
|
331
|
+
```bash
|
|
332
|
+
dm properties search --body '{"locations": [...], "filters": [...], "per_page": 25}' --json
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
For multiple searches, run them and then combine, compare, or present results as appropriate to the user's original intent.
|
|
336
|
+
|
|
337
|
+
### Step 7: Format Results
|
|
338
|
+
|
|
339
|
+
Present results in the format the user requested. Default to a clean summary table. Always show credit usage from the response.
|
|
340
|
+
|
|
341
|
+
### Step 8: Follow Up
|
|
342
|
+
|
|
343
|
+
Ask if they want to:
|
|
344
|
+
|
|
345
|
+
- See more results (next page)
|
|
346
|
+
- Narrow the search (add filters)
|
|
347
|
+
- Enrich specific results (get contacts)
|
|
348
|
+
- Export in a different format
|
|
349
|
+
|
|
350
|
+
---
|
|
351
|
+
|
|
352
|
+
## Natural Language Translation Guide
|
|
353
|
+
|
|
354
|
+
### Location Parsing
|
|
355
|
+
|
|
356
|
+
| User Says | CLI Location |
|
|
357
|
+
| ----------------------------------- | ----------------------------------------------------------------------------------- |
|
|
358
|
+
| "in Texas" / "in TX" | `{"type": "state", "code": "TX"}` |
|
|
359
|
+
| "in ZIP 78704" / "in 78704" | `{"type": "zip_code", "code": "78704"}` |
|
|
360
|
+
| "within 5 miles of downtown Austin" | `{"type": "radius", "latitude": 30.2672, "longitude": -97.7431, "radius_miles": 5}` |
|
|
361
|
+
| "in Travis County" | `{"type": "county", "code": "48453"}` (need FIPS code) |
|
|
362
|
+
|
|
363
|
+
**Important:** When user gives a city name, convert to ZIP codes or radius. The API does not support city names directly — use a radius around the city center or the relevant ZIP codes.
|
|
364
|
+
|
|
365
|
+
### Common Filter Translations
|
|
366
|
+
|
|
367
|
+
| User Says | Filter |
|
|
368
|
+
| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
369
|
+
| "worth over $500K" / "valued above 500K" | `{"filter_id": "estimated_value", "operator": "greater_than", "value": 500000}` |
|
|
370
|
+
| "worth between 200K and 500K" | `{"filter_id": "estimated_value", "operator": "range", "value": {"min": 200000, "max": 500000}}` |
|
|
371
|
+
| "3+ bedrooms" / "at least 3 beds" | `{"filter_id": "num_bedrooms", "operator": "greater_than_or_equal", "value": 3}` |
|
|
372
|
+
| "built before 1990" | `{"filter_id": "year_built", "operator": "less_than", "value": 1990}` |
|
|
373
|
+
| "owner-occupied" | `{"filter_id": "owner_occupied", "operator": "equals", "value": true}` |
|
|
374
|
+
| "absentee owners" / "not owner-occupied" | `{"filter_id": "owner_occupied", "operator": "equals", "value": false}` |
|
|
375
|
+
| "high equity" / "lots of equity" | `{"filter_id": "estimated_equity_percentage", "operator": "greater_than", "value": 50}` |
|
|
376
|
+
| "free and clear" / "no mortgage" | `{"filter_id": "num_mortgages", "operator": "equals", "value": 0}` |
|
|
377
|
+
| "sold in the last year" | `{"filter_id": "last_sale_date", "operator": "relative_time", "value": "last_12_months"}` |
|
|
378
|
+
|
|
379
|
+
**When unsure about a filter:** Run `dm filters --source-type properties --search "<keyword>" --json` to find matching filters. Always verify the filter exists before using it.
|
|
380
|
+
|
|
381
|
+
### Contact Audience Selection
|
|
382
|
+
|
|
383
|
+
| User Says | Audience |
|
|
384
|
+
| ----------------------------------- | ------------------- |
|
|
385
|
+
| "find the owners" / "who owns this" | `owners` |
|
|
386
|
+
| "owner and their family" | `owners_and_family` |
|
|
387
|
+
| "who rents there" / "tenants" | `renters` |
|
|
388
|
+
| "who lives there" / "residents" | `residents` |
|
|
389
|
+
|
|
390
|
+
**Credit impact:** Property-shaped results cost 1 property data credit per property, and contacts in `contact_audience` consume people credits. If the user wants a Contact List, Phone List, or Email List, charge 1 people data credit per distinct contact even when property filters created the list.
|
|
391
|
+
|
|
392
|
+
### Export Defaults
|
|
393
|
+
|
|
394
|
+
For property criteria or property lists, export **property-owner contacts by default**, not property rows.
|
|
395
|
+
|
|
396
|
+
Default request shape:
|
|
397
|
+
|
|
398
|
+
```json
|
|
399
|
+
{
|
|
400
|
+
"contact_audience": "owners",
|
|
401
|
+
"anchor": "person"
|
|
402
|
+
}
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
Default columns should include owner/contact name, phone numbers, emails, and the associated property address. Use:
|
|
406
|
+
|
|
407
|
+
- `anchor: "phone"` for call lists
|
|
408
|
+
- `anchor: "email"` for email lists
|
|
409
|
+
- `anchor: "property"` only when the user explicitly asks for one row per property
|
|
410
|
+
- `contact_audience: "none"` only when the user explicitly asks to exclude contact info
|
|
411
|
+
|
|
412
|
+
Always run the free count first and confirm before large exports.
|
|
413
|
+
|
|
414
|
+
### Comps Request Translation
|
|
415
|
+
|
|
416
|
+
| User Says | CLI Command |
|
|
417
|
+
| ----------------------------------------- | ---------------------------------------------------------------------- |
|
|
418
|
+
| "find comps for prop_12345" | `dm comps prop_12345` |
|
|
419
|
+
| "what's this house worth?" (has address) | Enrich address first, then `dm comps prop_xxx` |
|
|
420
|
+
| "CMA within 3 miles, last year" | `dm comps prop_xxx --radius 3 --timeframe 12months` |
|
|
421
|
+
| "comparable sales including foreclosures" | `dm comps prop_xxx --include-foreclosures` |
|
|
422
|
+
| "top 50 closest comps" | `dm comps prop_xxx --limit 50 --sort-by distance --sort-direction asc` |
|
|
423
|
+
| "comps for multiple properties" | `dm comps prop_111 prop_222 prop_333` |
|
|
424
|
+
|
|
425
|
+
**Credit impact:** 1 property data credit per subject property. The comps themselves are free. Much cheaper than a property search.
|
|
426
|
+
|
|
427
|
+
---
|
|
428
|
+
|
|
429
|
+
## Credit System Reference
|
|
430
|
+
|
|
431
|
+
### What Costs Credits
|
|
432
|
+
|
|
433
|
+
| Operation | Cost |
|
|
434
|
+
| --------------------------------------------------- | ----------------------------------------------- |
|
|
435
|
+
| Property search (per property returned) | 1 property data credit |
|
|
436
|
+
| Comps analysis (per subject property) | 1 credit |
|
|
437
|
+
| Person search (per person returned) | 1 people data credit |
|
|
438
|
+
| Contacts nested under property (`contact_audience`) | 1 people data credit per returned contact |
|
|
439
|
+
| Property on person (`include_properties`) | 1 credit each |
|
|
440
|
+
| Enrichment match (address, phone, email, etc.) | 1 data credit by result shape |
|
|
441
|
+
| Address validation (valid or corrected only) | 1 property data credit |
|
|
442
|
+
|
|
443
|
+
### What's FREE
|
|
444
|
+
|
|
445
|
+
| Operation | Cost |
|
|
446
|
+
| ----------------------------------------------------------------- | ------------------- |
|
|
447
|
+
| `dm properties count` | FREE |
|
|
448
|
+
| `dm people count` | FREE |
|
|
449
|
+
| `dm filters` | FREE |
|
|
450
|
+
| `dm fields` | FREE |
|
|
451
|
+
| `dm usage` | FREE |
|
|
452
|
+
| `dm account` | FREE |
|
|
453
|
+
| `dm whoami` | FREE |
|
|
454
|
+
| `dm activity search` / `dm activity get` | FREE |
|
|
455
|
+
| `dm lists search` / `get` / `create` / `add` / `remove` / `items` | FREE |
|
|
456
|
+
| Comps returned (only subject property costs) | FREE |
|
|
457
|
+
| Re-accessing same entity in same billing cycle | FREE (deduplicated) |
|
|
458
|
+
| Enrichment with no match | FREE |
|
|
459
|
+
| Invalid address validation | FREE |
|
|
460
|
+
| Using `estimate_cost: true` on searches | FREE |
|
|
461
|
+
|
|
462
|
+
### Credit Plans
|
|
463
|
+
|
|
464
|
+
| Plan | Credits/Month |
|
|
465
|
+
| ------- | ------------- |
|
|
466
|
+
| Basic | 10,000/seat |
|
|
467
|
+
| Pro | 20,000/seat |
|
|
468
|
+
|
|
469
|
+
### Credit-Saving Strategies
|
|
470
|
+
|
|
471
|
+
1. **Count before search** — Always use count endpoints first (free)
|
|
472
|
+
2. **Use `estimate_cost`** — Add to search body to preview cost without executing
|
|
473
|
+
3. **Choose the right output shape** — Property results charge per property and returned contact; flattened contact lists charge per contact
|
|
474
|
+
4. **Page small** — Start with `per_page: 10` to sample results before pulling more
|
|
475
|
+
5. **Leverage deduplication** — Same entity in same billing month costs nothing extra
|
|
476
|
+
6. **Use filters aggressively** — Narrow results before executing to avoid wasted credits
|
|
477
|
+
7. **Validate addresses first** — Invalid addresses don't cost credits; validate before enriching
|
|
478
|
+
8. **Batch operations** — Enrichment endpoints accept up to 1,000 items per request
|
|
479
|
+
|
|
480
|
+
---
|
|
481
|
+
|
|
482
|
+
## CLI Command Reference
|
|
483
|
+
|
|
484
|
+
### Authentication
|
|
485
|
+
|
|
486
|
+
```bash
|
|
487
|
+
dm login # Browser OAuth device flow
|
|
488
|
+
dm login --key dm_sk_live_xxx # Direct API key
|
|
489
|
+
dm login --no-browser # Show code without opening browser
|
|
490
|
+
dm logout # Remove stored credentials
|
|
491
|
+
dm whoami # Show auth status
|
|
492
|
+
dm whoami --verify # Verify credentials with API
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
### Account & Usage
|
|
496
|
+
|
|
497
|
+
```bash
|
|
498
|
+
dm account # Account info
|
|
499
|
+
dm account --json # Account info as JSON
|
|
500
|
+
dm usage # Credit usage for current billing cycle
|
|
501
|
+
dm usage --json # Credit usage as JSON
|
|
502
|
+
```
|
|
503
|
+
|
|
504
|
+
### Properties
|
|
505
|
+
|
|
506
|
+
```bash
|
|
507
|
+
# Count (FREE)
|
|
508
|
+
dm properties count --body '{"locations": [...], "filters": [...]}'
|
|
509
|
+
dm properties count -f search.json
|
|
510
|
+
|
|
511
|
+
# Search (costs credits)
|
|
512
|
+
dm properties search --body '{"locations": [...], "filters": [...]}'
|
|
513
|
+
dm properties search -f search.json
|
|
514
|
+
dm properties search -f search.json --json
|
|
515
|
+
|
|
516
|
+
# Get by ID
|
|
517
|
+
dm properties get prop_12345
|
|
518
|
+
dm properties get prop_12345 --contact-audience owners
|
|
519
|
+
dm properties get prop_12345 --json
|
|
520
|
+
|
|
521
|
+
# Get multiple by IDs
|
|
522
|
+
dm properties ids prop_12345 prop_67890
|
|
523
|
+
dm properties ids --body '{"ids": ["prop_12345", "prop_67890"]}'
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
### Comps (Comparable Sales)
|
|
527
|
+
|
|
528
|
+
```bash
|
|
529
|
+
# Basic comps (1 property data credit per subject property, comps are free)
|
|
530
|
+
dm comps prop_12345
|
|
531
|
+
dm comps prop_12345 --json
|
|
532
|
+
|
|
533
|
+
# Multiple properties
|
|
534
|
+
dm comps prop_12345 prop_67890
|
|
535
|
+
|
|
536
|
+
# Custom search radius
|
|
537
|
+
dm comps prop_12345 --radius 3
|
|
538
|
+
|
|
539
|
+
# Custom timeframe
|
|
540
|
+
dm comps prop_12345 --timeframe 12months
|
|
541
|
+
|
|
542
|
+
# Custom limit and sort
|
|
543
|
+
dm comps prop_12345 --limit 50 --sort-by price --sort-direction asc
|
|
544
|
+
|
|
545
|
+
# Include foreclosures
|
|
546
|
+
dm comps prop_12345 --include-foreclosures
|
|
547
|
+
|
|
548
|
+
# Full control via JSON body
|
|
549
|
+
dm comps --body '{"property_ids": ["prop_12345"], "location": {"type": "radius", "radius_miles": 2}, "criteria": {"timeframe": "12months", "limit": 50}}'
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
### People
|
|
553
|
+
|
|
554
|
+
```bash
|
|
555
|
+
# Count (FREE)
|
|
556
|
+
dm people count --body '{"locations": [...], "filters": [...]}'
|
|
557
|
+
dm people count -f search.json
|
|
558
|
+
|
|
559
|
+
# Search (costs credits)
|
|
560
|
+
dm people search --body '{"locations": [...], "filters": [...]}'
|
|
561
|
+
dm people search -f search.json
|
|
562
|
+
|
|
563
|
+
# Get by ID
|
|
564
|
+
dm people get per_12345
|
|
565
|
+
dm people get per_12345 --include-properties
|
|
566
|
+
|
|
567
|
+
# Get multiple by IDs
|
|
568
|
+
dm people ids per_12345 per_67890
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
### Enrichment
|
|
572
|
+
|
|
573
|
+
```bash
|
|
574
|
+
# By address
|
|
575
|
+
dm enrich address "123 Main St, Austin TX 78704"
|
|
576
|
+
dm enrich address --body '{"data": [{"full_address": "123 Main St, Austin TX"}]}'
|
|
577
|
+
dm enrich address "123 Main St, Austin TX" --contact-audience owners
|
|
578
|
+
|
|
579
|
+
# By coordinates
|
|
580
|
+
dm enrich latlng "30.2598,-97.7544"
|
|
581
|
+
dm enrich latlng --contact-audience owners
|
|
582
|
+
|
|
583
|
+
# By APN
|
|
584
|
+
dm enrich apn "12345678"
|
|
585
|
+
|
|
586
|
+
# By email
|
|
587
|
+
dm enrich email "john@example.com"
|
|
588
|
+
dm enrich email "john@example.com" --include-properties
|
|
589
|
+
|
|
590
|
+
# By phone
|
|
591
|
+
dm enrich phone "5551234567"
|
|
592
|
+
dm enrich phone "5551234567" --include-properties
|
|
593
|
+
|
|
594
|
+
# By name
|
|
595
|
+
dm enrich name "John Smith"
|
|
596
|
+
dm enrich name "John Smith" --state TX
|
|
597
|
+
dm enrich name "John Smith" --zip 78704
|
|
598
|
+
dm enrich name "Smith" # Last name only
|
|
599
|
+
dm enrich name "John Smith" --include-properties
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
### Discovery (FREE)
|
|
603
|
+
|
|
604
|
+
```bash
|
|
605
|
+
dm filters # All filters
|
|
606
|
+
dm filters --source-type properties # Property filters only
|
|
607
|
+
dm filters --source-type people # People filters only
|
|
608
|
+
dm filters --search "equity" # Search filters by name
|
|
609
|
+
dm filters --json # JSON output
|
|
610
|
+
|
|
611
|
+
dm fields # All fields
|
|
612
|
+
dm fields --source-type properties # Property fields
|
|
613
|
+
dm fields --search "bedroom" # Search fields by name
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
### Address Validation
|
|
617
|
+
|
|
618
|
+
```bash
|
|
619
|
+
dm addresses validate "123 Main St, Austin TX"
|
|
620
|
+
dm addresses validate -f addresses.json
|
|
621
|
+
dm addresses validate --body '{"data": [{"full_address": "123 Main St"}]}'
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
### Lists (FREE except export)
|
|
625
|
+
|
|
626
|
+
```bash
|
|
627
|
+
# Search lists (FREE)
|
|
628
|
+
dm lists search # All lists
|
|
629
|
+
dm lists search --search "Austin" # Search by name
|
|
630
|
+
dm lists search --source-type properties # Filter by type
|
|
631
|
+
|
|
632
|
+
# Create a list
|
|
633
|
+
dm lists create --name "My List" # Empty list
|
|
634
|
+
dm lists create --name "My List" --ids 101,202,303 # Pre-populated (max 250, synchronous)
|
|
635
|
+
dm lists create --name "My List" --body '{"filters": [...], "locations": [...]}' # From search (async)
|
|
636
|
+
|
|
637
|
+
# Get list details (FREE)
|
|
638
|
+
dm lists get <list_id>
|
|
639
|
+
dm lists get <list_id> --json
|
|
640
|
+
|
|
641
|
+
# Update / Delete
|
|
642
|
+
dm lists update <list_id> --name "New Name"
|
|
643
|
+
dm lists delete <list_id>
|
|
644
|
+
|
|
645
|
+
# Add / Remove items (FREE)
|
|
646
|
+
dm lists add <list_id> --ids 101,202,303
|
|
647
|
+
dm lists add <list_id> --ids 101,202 --id-type internal_person_id
|
|
648
|
+
dm lists remove <list_id> --ids 101
|
|
649
|
+
|
|
650
|
+
# View items (FREE)
|
|
651
|
+
dm lists items <list_id>
|
|
652
|
+
dm lists items <list_id> --page 2 --per-page 50
|
|
653
|
+
|
|
654
|
+
# Export (costs credits; property lists default to owner contacts)
|
|
655
|
+
dm lists export <list_id>
|
|
656
|
+
dm lists export <list_id> --anchor person
|
|
657
|
+
dm lists export <list_id> --fields estimated_value,owner_full_name --anchor property
|
|
658
|
+
```
|
|
659
|
+
|
|
660
|
+
### Activity (FREE)
|
|
661
|
+
|
|
662
|
+
```bash
|
|
663
|
+
dm activity search # All recent activity
|
|
664
|
+
dm activity search -t search_properties # Filter by type
|
|
665
|
+
dm activity search -q "Austin" # Free-text search
|
|
666
|
+
dm activity get act_12345 # Specific activity record
|
|
667
|
+
```
|
|
668
|
+
|
|
669
|
+
### Configuration
|
|
670
|
+
|
|
671
|
+
```bash
|
|
672
|
+
dm config get # All config values
|
|
673
|
+
dm config get apiKey # Specific value
|
|
674
|
+
dm config set apiEnvironment local # Set environment
|
|
675
|
+
dm config path # Show config file path
|
|
676
|
+
```
|
|
677
|
+
|
|
678
|
+
### Global Options
|
|
679
|
+
|
|
680
|
+
Every command supports:
|
|
681
|
+
|
|
682
|
+
- `--json` — Raw JSON output (machine-readable)
|
|
683
|
+
- `--help` — Command-specific help
|
|
684
|
+
|
|
685
|
+
### Input Methods (for search/enrichment)
|
|
686
|
+
|
|
687
|
+
1. **Positional argument:** `dm enrich address "123 Main St"` (single item, quick)
|
|
688
|
+
2. **Inline JSON:** `dm properties search --body '{"locations": [...]}'`
|
|
689
|
+
3. **JSON file:** `dm properties search -f search.json`
|
|
690
|
+
4. **Stdin pipe:** `cat search.json | dm properties search`
|
|
691
|
+
|
|
692
|
+
---
|
|
693
|
+
|
|
694
|
+
## Search Request Format
|
|
695
|
+
|
|
696
|
+
### Property Search Body
|
|
697
|
+
|
|
698
|
+
```json
|
|
699
|
+
{
|
|
700
|
+
"locations": [{ "type": "zip_code", "code": "78704" }],
|
|
701
|
+
"filters": [
|
|
702
|
+
{
|
|
703
|
+
"filter_id": "estimated_value",
|
|
704
|
+
"operator": "range",
|
|
705
|
+
"value": { "min": 200000, "max": 500000 }
|
|
706
|
+
},
|
|
707
|
+
{ "filter_id": "num_bedrooms", "operator": "greater_than_or_equal", "value": 3 }
|
|
708
|
+
],
|
|
709
|
+
"fields": ["estimated_value", "year_built", "living_area_sqft"],
|
|
710
|
+
"contact_audience": "owners",
|
|
711
|
+
"page": 1,
|
|
712
|
+
"per_page": 25,
|
|
713
|
+
"sort": [{ "field_id": "estimated_value", "direction": "desc" }]
|
|
714
|
+
}
|
|
715
|
+
```
|
|
716
|
+
|
|
717
|
+
### People Search Body
|
|
718
|
+
|
|
719
|
+
```json
|
|
720
|
+
{
|
|
721
|
+
"locations": [{ "type": "state", "code": "TX" }],
|
|
722
|
+
"filters": [{ "filter_id": "estimated_value", "operator": "greater_than", "value": 500000 }],
|
|
723
|
+
"property_match": "owner",
|
|
724
|
+
"page": 1,
|
|
725
|
+
"per_page": 25
|
|
726
|
+
}
|
|
727
|
+
```
|
|
728
|
+
|
|
729
|
+
### Filter Logic
|
|
730
|
+
|
|
731
|
+
- **Locations:** OR logic (match if in ANY location)
|
|
732
|
+
- **Filters:** AND logic (ALL filters must match)
|
|
733
|
+
- For OR-like behavior within a filter, use `contains_any` or `any_of` operators
|
|
734
|
+
|
|
735
|
+
### Filter Types & Operators
|
|
736
|
+
|
|
737
|
+
**NUMBER filters:** `range` (min/max), `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `equals`, `not_equals`
|
|
738
|
+
|
|
739
|
+
**STRING filters:** `contains`, `any_of`, `starts_with`, `ends_with`, `equals`, `not_equals`, `not_contains`
|
|
740
|
+
|
|
741
|
+
**DATE filters:** `date_range` (start_date/end_date), `is_after`, `is_before`, `equals`, `relative_time`
|
|
742
|
+
|
|
743
|
+
**MULTI_SELECT filters:** `contains_any`, `contains_none`, `contains_all`
|
|
744
|
+
|
|
745
|
+
**BOOLEAN filters:** No operator needed — just pass `true` or `false` as value
|
|
746
|
+
|
|
747
|
+
---
|
|
748
|
+
|
|
749
|
+
## Enrichment Batch Format
|
|
750
|
+
|
|
751
|
+
### Address Batch
|
|
752
|
+
|
|
753
|
+
```json
|
|
754
|
+
{
|
|
755
|
+
"data": [
|
|
756
|
+
{ "full_address": "123 Main St, Austin TX 78704" },
|
|
757
|
+
{ "street": "456 Oak Ave", "city": "Dallas", "state": "TX", "zip": "75201" }
|
|
758
|
+
],
|
|
759
|
+
"contact_audience": "owners"
|
|
760
|
+
}
|
|
761
|
+
```
|
|
762
|
+
|
|
763
|
+
### Phone Batch
|
|
764
|
+
|
|
765
|
+
```json
|
|
766
|
+
{
|
|
767
|
+
"data": [{ "phone": "5551234567" }, { "phone": "5559876543" }],
|
|
768
|
+
"include_properties": true
|
|
769
|
+
}
|
|
770
|
+
```
|
|
771
|
+
|
|
772
|
+
### Name Search
|
|
773
|
+
|
|
774
|
+
```json
|
|
775
|
+
{
|
|
776
|
+
"data": [{ "last_name": "Smith", "first_name": "John" }],
|
|
777
|
+
"location": { "type": "state", "code": "TX" },
|
|
778
|
+
"include_properties": false,
|
|
779
|
+
"page": 1,
|
|
780
|
+
"per_page": 25
|
|
781
|
+
}
|
|
782
|
+
```
|
|
783
|
+
|
|
784
|
+
All enrichment endpoints accept up to **250 items** per request. The CLI auto-batches larger inputs.
|
|
785
|
+
|
|
786
|
+
---
|
|
787
|
+
|
|
788
|
+
## Response Reading Guide
|
|
789
|
+
|
|
790
|
+
### Credits Object
|
|
791
|
+
|
|
792
|
+
Every credit-consuming response includes:
|
|
793
|
+
|
|
794
|
+
```json
|
|
795
|
+
{
|
|
796
|
+
"credits": {
|
|
797
|
+
"used": 27,
|
|
798
|
+
"properties": 25,
|
|
799
|
+
"people": 20,
|
|
800
|
+
"deduplicated": 3
|
|
801
|
+
}
|
|
802
|
+
}
|
|
803
|
+
```
|
|
804
|
+
|
|
805
|
+
- `used` — total credits consumed this request
|
|
806
|
+
- `people` — contacts included under property leads and charged as people credits
|
|
807
|
+
- `deduplicated` — credits saved because entity was accessed earlier this billing cycle
|
|
808
|
+
|
|
809
|
+
### Pagination
|
|
810
|
+
|
|
811
|
+
```json
|
|
812
|
+
{
|
|
813
|
+
"page": 1,
|
|
814
|
+
"per_page": 25,
|
|
815
|
+
"total_results": 847,
|
|
816
|
+
"total_pages": 34,
|
|
817
|
+
"has_next_page": true,
|
|
818
|
+
"has_previous_page": false
|
|
819
|
+
}
|
|
820
|
+
```
|
|
821
|
+
|
|
822
|
+
### Always-Included Property Fields
|
|
823
|
+
|
|
824
|
+
These fields are always returned, even without requesting `fields`:
|
|
825
|
+
|
|
826
|
+
- `dm_property_id`, `full_address`, `address`, `unit`, `city`, `state`, `zip`
|
|
827
|
+
- `latitude`, `longitude`
|
|
828
|
+
- `images` (street_view, satellite, roadmap URLs)
|
|
829
|
+
|
|
830
|
+
### Always-Included Person Fields
|
|
831
|
+
|
|
832
|
+
- `dm_person_id`, `full_name`, `first_name`, `last_name`
|
|
833
|
+
- `phones` (array: number, type, do_not_call)
|
|
834
|
+
- `emails` (array: address)
|
|
835
|
+
- `residence` (address, city, state, zip, full_address)
|
|
836
|
+
|
|
837
|
+
---
|
|
838
|
+
|
|
839
|
+
## Multi-Step Workflow Examples
|
|
840
|
+
|
|
841
|
+
### Example 1: Build a Mailing List
|
|
842
|
+
|
|
843
|
+
**User:** "Find absentee owners with high equity in Austin 78704 and get their contact info"
|
|
844
|
+
|
|
845
|
+
**Workflow:**
|
|
846
|
+
|
|
847
|
+
1. Count: `dm properties count --body '{"locations": [{"type": "zip_code", "code": "78704"}], "filters": [{"filter_id": "owner_occupied", "operator": "equals", "value": false}, {"filter_id": "estimated_equity_percentage", "operator": "greater_than", "value": 50}]}'`
|
|
848
|
+
2. Report: "Found 312 absentee-owned properties with >50% equity in 78704. Getting first 25 with owner contacts would cost ~75-175 credits depending on contacts per property. Proceed?"
|
|
849
|
+
3. Execute: `dm properties search --body '...' --json`
|
|
850
|
+
4. Format as mailing list (name, mailing address)
|
|
851
|
+
|
|
852
|
+
### Example 2: Look Up a Specific Property
|
|
853
|
+
|
|
854
|
+
**User:** "Who owns 742 Evergreen Terrace, Springfield?"
|
|
855
|
+
|
|
856
|
+
**Workflow:**
|
|
857
|
+
|
|
858
|
+
1. Enrich: `dm enrich address "742 Evergreen Terrace, Springfield" --contact-audience owners --json`
|
|
859
|
+
2. Cost: 1 credit for property + 1 per owner found
|
|
860
|
+
3. Present: Owner name, phone, email, property details
|
|
861
|
+
|
|
862
|
+
### Example 3: Reverse Phone Lookup
|
|
863
|
+
|
|
864
|
+
**User:** "Who is 555-123-4567?"
|
|
865
|
+
|
|
866
|
+
**Workflow:**
|
|
867
|
+
|
|
868
|
+
1. Enrich: `dm enrich phone "5551234567" --include-properties --json`
|
|
869
|
+
2. Cost: 1 credit for person + 1 per property
|
|
870
|
+
3. Present: Person's name, other phones, emails, associated properties
|
|
871
|
+
|
|
872
|
+
### Example 4: Market Analysis (Credit-Efficient)
|
|
873
|
+
|
|
874
|
+
**User:** "How many homes worth over $1M are in Travis County?"
|
|
875
|
+
|
|
876
|
+
**Workflow:**
|
|
877
|
+
|
|
878
|
+
1. Count only: `dm people count --body '{"locations": [{"type": "county", "code": "48453"}], "filters": [{"filter_id": "estimated_value", "operator": "greater_than", "value": 1000000}]}'`
|
|
879
|
+
2. Cost: FREE — count endpoints don't consume credits
|
|
880
|
+
3. Present: "There are 4,231 properties valued over $1M in Travis County."
|
|
881
|
+
|
|
882
|
+
### Example 5: Batch Enrichment
|
|
883
|
+
|
|
884
|
+
**User:** "Look up these 50 addresses from my file"
|
|
885
|
+
|
|
886
|
+
**Workflow:**
|
|
887
|
+
|
|
888
|
+
1. Read the file to count addresses
|
|
889
|
+
2. Report: "50 addresses. This will cost up to 50 credits for property data (less if some don't match). Add contacts?"
|
|
890
|
+
3. Execute: `dm enrich address -f addresses.json --json`
|
|
891
|
+
4. Report matches vs. no-matches and credits used
|
|
892
|
+
|
|
893
|
+
### Example 6: Property Valuation / CMA
|
|
894
|
+
|
|
895
|
+
**User:** "What's 742 Evergreen Terrace worth? Show me the comps."
|
|
896
|
+
|
|
897
|
+
**Workflow:**
|
|
898
|
+
|
|
899
|
+
1. Enrich: `dm enrich address "742 Evergreen Terrace, Springfield" --json` → get `prop_xxx` (1 credit)
|
|
900
|
+
2. Comps: `dm comps prop_xxx --json` (1 credit for subject)
|
|
901
|
+
3. Present: value estimation with confidence interval, summary stats (avg price, median, $/sqft), and comp table
|
|
902
|
+
4. Total cost: 2 credits
|
|
903
|
+
|
|
904
|
+
### Example 7: Investor ARV Analysis
|
|
905
|
+
|
|
906
|
+
**User:** "Find comps for this flip within 2 miles, only recent sales, no foreclosures"
|
|
907
|
+
|
|
908
|
+
**Workflow:**
|
|
909
|
+
|
|
910
|
+
1. Get property ID (enrich if needed)
|
|
911
|
+
2. Run: `dm comps prop_xxx --radius 2 --timeframe 6months --json`
|
|
912
|
+
3. The default excludes foreclosures, so no extra flag needed
|
|
913
|
+
4. Present value estimation as the ARV, highlight price per sqft for renovation budgeting
|
|
914
|
+
|
|
915
|
+
### Example 8: Save Search Results to a List
|
|
916
|
+
|
|
917
|
+
**User:** "Save those properties to a list called 'Austin Targets'"
|
|
918
|
+
|
|
919
|
+
**Workflow:**
|
|
920
|
+
|
|
921
|
+
1. Collect property IDs from the previous search results (up to 250)
|
|
922
|
+
2. Create: `dm lists create --name "Austin Targets" --ids 101,202,303,...` (synchronous, returns completed)
|
|
923
|
+
3. Cost: FREE — no credits charged for list creation
|
|
924
|
+
4. Present: list ID, name, total count, and link
|
|
925
|
+
|
|
926
|
+
### Example 9: Build a Large List from Filters
|
|
927
|
+
|
|
928
|
+
**User:** "Create a list of all properties in 78704 with >50% equity"
|
|
929
|
+
|
|
930
|
+
**Workflow:**
|
|
931
|
+
|
|
932
|
+
1. Count first: `dm properties count --body '{"locations": [...], "filters": [...]}'` (FREE)
|
|
933
|
+
2. Report: "Found 2,341 matches. Creating a list is free. Proceed?"
|
|
934
|
+
3. Create: `dm lists create --name "High Equity 78704" --body '{"filters": [...], "locations": [...]}'` (async)
|
|
935
|
+
4. Poll: `dm lists get <list_id> --json` until status is `"completed"`
|
|
936
|
+
5. Cost: FREE — list creation doesn't consume credits. Credits only charged at export time.
|