> ## 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 People by IDs

Retrieve multiple people by their DealMachine person IDs in a single request. Use this when you already have `dm_person_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 person IDs to retrieve (max 250).

  Example: `["per_12345", "per_67890"]`
</ParamField>

<ParamField body="enrich" type="boolean" default={true}>
  Controls whether enriched data is returned and credits are consumed.

  Set `true` (default) to return person fields including phones, emails, and demographics. Credits are consumed per entity. Set `false` for preview mode with base fields only. Preview mode omits phones, emails, and demographic data and consumes no credits.
</ParamField>

<ParamField body="include_properties" type="boolean" default={false}>
  When `true`, each found person includes a `properties` array with all associated properties.
</ParamField>

<ParamField body="property_limit" type="integer" default={20}>
  Maximum associated properties to return per person when `include_properties=true`. Maximum: 100.
</ParamField>

<ParamField body="fields" type="string[]">
  Field IDs from [List Fields](/api-reference/fields/list-fields). People fields return on each person. Property fields return under `property`.
</ParamField>

***

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.v2.dealmachine.com/v1/people/ids" \
    -H "Authorization: Bearer dm_sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "ids": ["per_12345", "per_67890"],
      "include_properties": true,
      "property_limit": 20,
      "fields": ["estimated_household_income", "estimated_value"]
    }'
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.v2.dealmachine.com/v1/people/ids', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      ids: ['per_12345', 'per_67890'],
      include_properties: true,
      property_limit: 20,
      fields: ['estimated_household_income', 'estimated_value'],
    }),
  });

  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.full_name} — ${item.phones?.[0]?.number}`);
    } else {
      console.log(`Not found: ${item.dm_person_id}`);
    }
  }
  ```

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

  response = requests.post(
      "https://api.v2.dealmachine.com/v1/people/ids",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "ids": ["per_12345", "per_67890"],
          "include_properties": True,
          "property_limit": 20,
          "fields": ["estimated_household_income", "estimated_value"],
      },
  )

  body = response.json()
  print(f"Found {body['totals']['found']} of {body['totals']['submitted']}")
  for item in body["data"]:
      if item["found"]:
          print(f"{item['full_name']} — {item.get('phones', [{}])[0].get('number', 'N/A')}")
      else:
          print(f"Not found: {item['dm_person_id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "dm_person_id": "per_12345",
        "found": true,
        "full_name": "John Smith",
        "first_name": "John",
        "last_name": "Smith",
        "person_age": 45,
        "phones": [{ "number": "5125551234", "type": "wireless", "do_not_call": false }],
        "emails": [{ "address": "john@example.com" }],
        "properties": [
          {
            "dm_property_id": "prop_67890",
            "address": "1200 Barton Springs Rd",
            "city": "Austin",
            "state": "TX",
            "zip": "78704",
            "estimated_value": 575000,
            "is_likely_owner": true
          }
        ]
      },
      {
        "dm_person_id": "per_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 person data with contact information.

| Field                        | Type    | Description                                                                                           |
| ---------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `dm_person_id`               | string  | DealMachine person ID                                                                                 |
| `found`                      | boolean | `true`                                                                                                |
| `full_name`                  | string  | Full display name                                                                                     |
| `first_name`, `last_name`    | string  | Name components                                                                                       |
| `middle_initial`             | string  | Middle initial                                                                                        |
| `age`                        | number  | Estimated age                                                                                         |
| `estimated_household_income` | number  | Estimated household income                                                                            |
| `gender`                     | string  | Gender (e.g., `"Male"`, `"Female"`)                                                                   |
| `marital_status`             | string  | Marital status (e.g., `"Married"`, `"Single"`)                                                        |
| `education`                  | string  | Education level                                                                                       |
| `occupation`                 | string  | Occupation                                                                                            |
| `language`                   | string  | Primary language                                                                                      |
| `phones`                     | array   | Phone numbers with `number`, normalized `type`, and `do_not_call`                                     |
| `emails`                     | array   | Email addresses, each with `address`                                                                  |
| `property`                   | object  | Property context and requested property fields when `fields` includes property data.                  |
| `properties`                 | array   | Associated properties. Only present when `include_properties` is `true`. Limited by `property_limit`. |

### Not Found Result

| Field          | Type    | Description                           |
| -------------- | ------- | ------------------------------------- |
| `dm_person_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 people found  |
| `not_found` | integer | Number of IDs not found |

## Credits

When `enrich=true` (the default), this endpoint consumes 1 [people credit](/concepts/credits) per found person. When `include_properties` is true, included properties consume property credits. Chargeable property fields requested through `fields` add property 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 (name, match flags). No phones, emails, or demographic data is included.

## Notes

* Response order matches your input order.
* Invalid ID formats (e.g., missing `per_` 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 person, use [GET /v1/people/:id](/api-reference/people/get-person) instead.