> ## 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.
# Enrich by Address
Look up properties by street address. Each item in the `data` array can use either a single `full_address` string or structured components (`street`, `unit`, `city`, `state`, `zip`). You can also break down the street into `street_number` and `street_name` instead of using a single `street` field.
Each request accepts up to **250 items** in the `data` array. The response returns every submitted
item with a `matched` flag indicating whether a property was found.
## Body Parameters
Array of address objects to look up (max 250).
Complete address string (e.g., `"1200 Barton Springs Rd, Austin, TX 78704"`). Use this **or** the structured fields below — not both.
Street address line **only** — e.g., `"1200 Barton Springs Rd"`. Do not include city, state, or ZIP in this value; put those in the separate `city`, `state`, and `zip` fields. If you want to pass the whole address as one string, use `full_address` instead. Required when not using `full_address` or `street_number`/`street_name`.
If we detect that this field contains a full address line (e.g., `"1200 Barton Springs Rd Austin, TX 78704"`), we'll try to match on just the parsed street and attach a `match_warning` to the per-item response (see [`match_warning`](#match-warnings)).
Street number (e.g., `"1200"`). Use with `street_name` as an alternative to `street`.
Street name (e.g., `"Barton Springs Rd"`). Use with `street_number` as an alternative to `street`.
Unit, apartment, or suite number (e.g., `"Apt 4B"`, `"Suite 200"`). Optional.
City name. Required when not using `full_address`.
Two-letter state abbreviation. Required when not using `full_address`.
5-digit ZIP code. Optional when using structured fields, but improves match accuracy.
[Field IDs](/concepts/fields) to include in results. Can include both property and people fields.
Omit or pass an empty array for the default set.
Which contacts to include on matched properties.
Options: `owners`, `owners_and_family`, `renters`, `residents`, `none`
When set to an audience other than `none`, each matched result includes a `contacts` array. Omit the
parameter or set it to `none` to return property data only with zero people credits.
Use `contact_audience: "none"` when you only need the enriched property. Request `owners` or
another audience only when you need those people records.
***
```bash cURL theme={null}
curl -X POST "https://api.v2.dealmachine.com/v1/enrichment/address" \
-H "Authorization: Bearer dm_sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"data": [
{
"full_address": "1200 Barton Springs Rd, Austin, TX 78704"
},
{
"street": "4500 S Lamar Blvd",
"unit": "Apt 4B",
"city": "Austin",
"state": "TX",
"zip": "78745"
},
{
"street_number": "1600",
"street_name": "Pennsylvania Ave",
"city": "Washington",
"state": "DC",
"zip": "20500"
}
],
"fields": ["estimated_value", "equity_percent", "bedrooms", "full_name", "phones"],
"contact_audience": "owners"
}'
```
```typescript Node.js theme={null}
const response = await fetch('https://api.v2.dealmachine.com/v1/enrichment/address', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
data: [
{ full_address: '1200 Barton Springs Rd, Austin, TX 78704' },
{
street: '4500 S Lamar Blvd',
unit: 'Apt 4B',
city: 'Austin',
state: 'TX',
zip: '78745',
},
{
street_number: '1600',
street_name: 'Pennsylvania Ave',
city: 'Washington',
state: 'DC',
zip: '20500',
},
],
fields: ['estimated_value', 'equity_percent', 'bedrooms', 'full_name', 'phones'],
contact_audience: 'owners',
}),
});
const { data, totals } = await response.json();
console.log(`Matched ${totals.matched} of ${totals.submitted}`);
for (const item of data) {
if (item.matched) {
console.log(`${item.full_address} — $${item.estimated_value.toLocaleString()}`);
for (const contact of item.contacts) {
console.log(` → ${contact.full_name}: ${contact.phones[0]?.number}`);
}
} else {
console.log(`No match: ${item.input.full_address || item.input.street}`);
}
}
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.v2.dealmachine.com/v1/enrichment/address",
headers={"Authorization": f"Bearer {api_key}"},
json={
"data": [
{"full_address": "1200 Barton Springs Rd, Austin, TX 78704"},
{
"street": "4500 S Lamar Blvd",
"unit": "Apt 4B",
"city": "Austin",
"state": "TX",
"zip": "78745",
},
{
"street_number": "1600",
"street_name": "Pennsylvania Ave",
"city": "Washington",
"state": "DC",
"zip": "20500",
},
],
"fields": [
"estimated_value",
"equity_percent",
"bedrooms",
"full_name",
"phones",
],
"contact_audience": "owners",
},
)
body = response.json()
for item in body["data"]:
if item["matched"]:
print(f"{item['full_address']} — ${item['estimated_value']:,}")
for contact in item["contacts"]:
print(f" → {contact['full_name']}: {contact['phones'][0]['number']}")
else:
addr = item["input"].get("full_address") or item["input"].get("street")
print(f"No match: {addr}")
```
```json 200 OK theme={null}
{
"data": [
{
"input": {
"full_address": "1200 Barton Springs Rd, Austin, TX 78704"
},
"matched": true,
"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,
"equity_percent": 72,
"bedrooms": 4,
"contacts": [
{
"dm_person_id": "per_x1y2z3",
"full_name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"phones": [{ "number": "5125551234", "type": "wireless", "do_not_call": false }],
"emails": [{ "address": "john.smith@example.com" }],
"is_likely_owner": true,
"is_in_owner_family": false,
"is_resident": true,
"is_likely_renter": false
}
]
},
{
"input": {
"street": "999 Nonexistent Ave",
"city": "Austin",
"state": "TX",
"zip": "78700"
},
"matched": false,
"match_failure": {
"code": "not_found",
"reason": "No property found matching the provided address"
}
}
],
"totals": {
"submitted": 2,
"matched": 1,
"unmatched": 1
},
"credits": {
"used": 2,
"properties": 1,
"people": 1,
"deduplicated": 0
}
}
```
```json 400 Validation Error theme={null}
{
"error": {
"code": "validation_error",
"message": "Validation failed",
"request_id": "req_abc123def456",
"details": {
"issues": [
{
"path": "data[1]",
"message": "Provide either full_address or street + city + state"
}
]
}
}
}
```
```json 401 Unauthorized theme={null}
{
"error": {
"code": "invalid_api_key",
"message": "The provided API key is invalid",
"request_id": "req_def456ghi789"
}
}
```
```json 429 Rate Limited theme={null}
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Please retry after the specified time.",
"request_id": "req_ghi789jkl012"
}
}
```
## Response Fields
The response contains a `data` array and a `totals` object. There is no pagination — all submitted items are returned in a single response.
### Matched Result
When `matched` is `true`, the result contains all [always-included property fields](/concepts/response-format#properties) plus any requested fields.
| Field | Type | Description |
| --------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `input` | object | Echo of the original input object |
| `matched` | boolean | `true` |
| `dm_property_id` | string | DealMachine internal property ID |
| `full_address` | string | Complete formatted address |
| `address`, `city`, `state`, `zip` | string | Parsed address components |
| `latitude`, `longitude` | number | Property coordinates |
| `images` | object | Signed URLs for `street_view`, `satellite`, and `roadmap` |
| `contacts` | array | Contacts matching `contact_audience`. Omitted for `contact_audience: "none"`. |
| *requested fields* | varies | Any fields specified in `fields` |
### Unmatched Result
| Field | Type | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------------------- |
| `input` | object | Echo of the original input object |
| `matched` | boolean | `false` |
| `match_failure` | object | Structured failure with `code` and `reason` |
| `match_failure.code` | string | Machine-readable failure code (see [Match Failure Codes](#match-failure-codes) below) |
| `match_failure.reason` | string | Human-readable explanation of why no match was found |
### Match Warnings
When the API can still match an item but had to rewrite the input to do so, the response item includes a `match_warning` alongside `matched` (whether the match succeeded or not). Treat it as a signal to fix your client — the match worked this time but may not on a similar input.
| Field | Type | Description |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| `match_warning.code` | string | Machine-readable warning code (e.g., `street_field_contains_full_address`) |
| `match_warning.message` | string | Human-readable explanation |
| `match_warning.hint` | object | Endpoint-specific hint — for `street_field_contains_full_address`, includes `parsed_street` with what we used |
### Match Failure Codes
These codes are shared across all enrichment endpoints.
| Code | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `not_found` | No matching record exists for the provided input |
| `invalid_input` | The input could not be processed (e.g., invalid address, invalid email, invalid phone number). The `reason` field provides specifics. |
### Totals
| Field | Type | Description |
| ----------- | ------- | ------------------------------------------- |
| `submitted` | integer | Number of items in the request `data` array |
| `matched` | integer | Number of items that matched a property |
| `unmatched` | integer | Number of items that did not match |
## Credits
This endpoint consumes 1 [property data credit](/concepts/credits) per matched property. When `contact_audience` is set to an audience other than `none`, included contacts consume people credits. `contact_audience: "none"` consumes zero people credits. Only matched results consume credits. Credits are deduplicated within your billing period.
Every response includes a `credits` object with a full breakdown of what was charged. See [Credits](/concepts/credits) for details.
## Notes
* Each item must include either `full_address`, `street`, or the combination of `street_number` + `street_name`, along with `city` + `state`. Including `unit` and `zip` with structured fields is optional but improves match accuracy.
* Items are matched independently — one failed match does not affect others.
* The `input` object is always echoed back so you can correlate results with your input data.
* When `contact_audience` is set to an audience other than `none`, each matched result includes a `contacts` array with the same structure and match behavior as [Search Properties](/api-reference/properties/search-properties#contact-match-status).