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.

Each request accepts up to 250 IDs. The response preserves your input order and includes a found flag for each item.

Body Parameters

body idsstring[]required

Array of DealMachine person IDs to retrieve (max 250).

Example: ["per_12345", "per_67890"]

body enrichbooleandefault:

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.

body include_propertiesboolean

When true, each found person includes a properties array with all associated properties.

body property_limitintegerdefault: 20

Maximum associated properties to return per person when include_properties=true. Maximum: 100.

body fieldsstring[]

Field IDs from List Fields. People fields return on each person. Property fields return under property.

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

Request example

123456789curl -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"]
  }'

Response example

12345678910111213141516171819202122232425262728293031323334353637383940{
  "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
  }
}