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

# Get Properties by IDs

Retrieve multiple properties by their DealMachine property IDs in a single request. Use this when you already have `dm_property_id` values from a previous search or enrichment and want to fetch current data.

<Note>
  Each request accepts up to **250 IDs**. The response preserves your input order and includes a
  `found` flag for each item.
</Note>

## Body Parameters

<ParamField body="ids" type="string[]" required>
  Array of DealMachine property IDs to retrieve (max 250).

  Example: `["prop_12345", "prop_67890"]`
</ParamField>

<ParamField body="enrich" type="boolean" default={true}>
  Controls whether enriched data is returned and credits are consumed. `true` (default) returns
  enriched property fields plus contacts selected by `contact_audience`, with credits consumed per
  entity. `false` enables preview mode and returns only base fields (address, coordinates, images,
  bedrooms, bathrooms, and sqft) without consuming credits.
</ParamField>

<ParamField body="contact_audience" type="string" default="owners">
  Which contacts to include with found properties. Defaults to `"owners"`.

  Options: `owners`, `owners_and_family`, `renters`, `residents`, `all`, `none`

  When set (and not `"none"`), each found result includes a `contacts` array with match type flags. Use `all` to return every associated contact. Returned contacts consume people credits. Set to `"none"` to skip contacts.
</ParamField>

<Tip>
  If you only need property data, set `contact_audience` to `none`. Each result omits `contacts`,
  skips contact lookup, and consumes zero people credits.
</Tip>

***

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.v2.dealmachine.com/v1/properties/ids" \
    -H "Authorization: Bearer dm_sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "ids": ["prop_12345", "prop_67890"],
      "contact_audience": "owners"
    }'
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.v2.dealmachine.com/v1/properties/ids', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      ids: ['prop_12345', 'prop_67890'],
      contact_audience: 'owners',
    }),
  });

  const { data, totals } = await response.json();

  console.log(`Found ${totals.found} of ${totals.submitted}`);
  for (const item of data) {
    if (item.found) {
      console.log(
        `${item.dm_property_id} — ${item.full_address} — $${item.estimated_value?.toLocaleString()}`
      );
    } else {
      console.log(`Not found: ${item.dm_property_id}`);
    }
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.v2.dealmachine.com/v1/properties/ids",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "ids": ["prop_12345", "prop_67890"],
          "contact_audience": "owners",
      },
  )

  body = response.json()
  print(f"Found {body['totals']['found']} of {body['totals']['submitted']}")
  for item in body["data"]:
      if item["found"]:
          print(f"{item['dm_property_id']} — {item['full_address']} — ${item['estimated_value']:,}")
      else:
          print(f"Not found: {item['dm_property_id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "dm_property_id": "prop_12345",
        "found": true,
        "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,
        "estimated_value": 575000,
        "estimated_equity_amount": 414000,
        "estimated_equity_percentage": 72,
        "year_built": 1985,
        "living_area_sqft": 2200,
        "lot_size_sqft": 8500,
        "num_bedrooms": 4,
        "num_bathrooms": 2,
        "owner_occupied": true,
        "contacts": [
          {
            "dm_person_id": "per_67890",
            "full_name": "John Smith",
            "first_name": "John",
            "last_name": "Smith",
            "phones": [{ "number": "5125551234", "type": "wireless", "do_not_call": false }]
          }
        ]
      },
      {
        "dm_property_id": "prop_99999",
        "found": false
      }
    ],
    "totals": {
      "submitted": 2,
      "found": 1,
      "not_found": 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_abc123"
    }
  }
  ```
</ResponseExample>

## Response Fields

### Found Result

When `found` is `true`, the result contains comprehensive property data.

| Field                             | Type    | Description                                                   |
| --------------------------------- | ------- | ------------------------------------------------------------- |
| `dm_property_id`                  | string  | DealMachine property ID                                       |
| `found`                           | boolean | `true`                                                        |
| `full_address`                    | string  | Complete formatted address                                    |
| `address`, `city`, `state`, `zip` | string  | Parsed address components                                     |
| `latitude`, `longitude`           | number  | Property coordinates                                          |
| `estimated_value`                 | number  | Estimated market value                                        |
| `estimated_equity_amount`         | number  | Estimated equity in dollars                                   |
| `estimated_equity_percentage`     | number  | Estimated equity as percentage                                |
| `year_built`                      | number  | Year built                                                    |
| `living_area_sqft`                | number  | Living area in sq ft                                          |
| `lot_size_sqft`                   | number  | Lot size in sq ft                                             |
| `num_bedrooms`, `num_bathrooms`   | number  | Bedroom/bathroom count                                        |
| `owner_occupied`                  | boolean | Whether owner lives at property                               |
| `last_sale_date`                  | string  | Date of last sale                                             |
| `last_sale_amount`                | number  | Last sale price                                               |
| `apn`                             | string  | Assessor's Parcel Number                                      |
| `fips`                            | string  | 5-digit FIPS county code                                      |
| `contacts`                        | array   | Contacts. Only present when `contact_audience` is not `none`. |

### Not Found Result

| Field            | Type    | Description                           |
| ---------------- | ------- | ------------------------------------- |
| `dm_property_id` | string  | The ID you submitted                  |
| `found`          | boolean | `false`                               |
| `error`          | object  | Present when the ID format is invalid |

### Totals

| Field       | Type    | Description                |
| ----------- | ------- | -------------------------- |
| `submitted` | integer | Number of IDs submitted    |
| `found`     | integer | Number of properties found |
| `not_found` | integer | Number of IDs not found    |

## Credits

When `enrich=true` (the default), this endpoint consumes 1 [property data credit](/concepts/credits) per found property. When `contact_audience` is set to a value other than `"none"` (default: `"owners"`), included contacts consume people credits. Not-found results are free. Credits are deduplicated within your billing period.

When `enrich=false`, no credits are consumed. Only base fields are returned (address, coordinates, images, bedrooms, bathrooms, sqft), and contacts include only names and match flags (no phones or emails).

## Notes

* Response order matches your input order.
* Invalid ID formats (e.g., missing `prop_` prefix) return an error object instead of a not-found result.
* Items are looked up independently. One failed lookup does not affect others.
* For a single property, use [GET /v1/properties/:id](/api-reference/properties/get-property) instead.