Enrich by Name

Look up people by name. Provide a data array of name objects (each with a last_name and optional first_name) and the API returns all matching people with their contact information. Optionally include a location to narrow results to a specific area.

Use this endpoint when you know the person's name. Search People is for filter-defined audiences and does not accept a person's name as a filter.

This endpoint returns paginated results: up to 100 people per page. Use page and per_page to navigate through large result sets.

Body Parameters

body dataarrayrequired

Array of name objects to search for (max 250). Each object must include a last_name.

Name object properties

body last_namestringrequired

Last name to search for (case-insensitive).

body first_namestring

First name to narrow results (case-insensitive). Omit to return all people with the matching last name.

body middle_initialstring

Single-character middle initial to narrow results (case-insensitive).

body locationobject

Location to narrow results to a specific area. When omitted, results are not filtered by location. Name lookup supports state, ZIP code, county, and city. For a city, first use the Locations endpoint to resolve the city name to its place ID, then pass that ID as the location code.

Location object properties

body typestringrequired

Location type: "state", "zip_code", "county", or "city".

body codestringrequired

Location code. For states, use the 2-letter abbreviation (e.g., "MO"). For ZIP codes, use the 5-digit code (e.g., "63101"). For counties, use the FIPS code (e.g., "29510"). For cities, use the place ID returned by the Locations endpoint (e.g., "53584").

body include_propertiesboolean

When true, each matched person includes a properties array with its associated properties (capped for very large portfolios, plus the primary residence when property fields are requested and it falls outside that cap).

body fieldsstring[]

Field IDs to include in results. People fields return on each person. Property fields return under property.

body pageintegerdefault: 1

Page number for pagination (starts at 1).

body per_pageintegerdefault: 25

Number of results per page (max 100).

body estimate_costboolean

When true, returns a match count and credit estimate without returning person data or consuming credits.

Response Fields

The response contains a data array of person contacts and a pagination object.

When estimate_cost is true, the response contains totals, pagination, and estimated_credits instead. It does not include data or credits, and it does not consume credits.

Person Contact

Each object in the data array contains:

Field	Type	Description
`dm_person_id`	string	DealMachine internal person ID
`full_name`	string	Full display name
`first_name`, `last_name`	string \| null	Parsed name components
`property_count`	integer	Number of associated properties. This count is free metadata.
`residence`	object \| null	Where the person lives (their mailing address). Always included with the people credit. `null` when no residence is on file. See Residence.
`property`	object	The person's primary residence, with the property fields you requested. Only present when `fields` includes property fields. See Primary Residence Property.
`phones`	array	Phone numbers with `number`, normalized `type`, `do_not_call`, and `carrier`
`emails`	array	Email addresses with `address`
`properties`	array	Associated properties. Only present when `include_properties` is `true`.

Residence

The residence object is where the person lives. It has the same fields as the residence object on people search results (values here use title case, such as Unit 1604) and costs nothing beyond the people credit.

Field	Type	Description
`address`	string \| null	Street address
`unit`	string \| null	Unit or apartment (e.g., "Unit 1604")
`city`	string \| null	City
`state`	string \| null	Two-letter state abbreviation
`zip`	string \| null	5-digit ZIP code
`full_address`	string \| null	Complete formatted address

Primary Residence Property

When fields includes property fields (for example estimated_value or is_owner_occupied), the nested property object is the person's primary residence. It is always one of the person's linked properties, so it also appears in properties when include_properties is true. DealMachine picks it in this order:

The linked property at the residence address (street, unit, and ZIP).
The linked property at the residence street and ZIP, when the unit differs.
The linked property the person is flagged as living in.
The person's owner-occupied property, then any property they own, then a property owned by their family, then any other linked property.

When the person has no linked properties, property is omitted and no property credit is charged.

Pagination

Field	Type	Description
`page`	integer	Current page number
`per_page`	integer	Results per page
`total`	integer	Total number of matching people
`total_pages`	integer	Total number of pages

Credits

Credits are charged per matched person:

What you request	What you get	Credits
No property fields	Person data and `residence`	1 people credit
Property fields in `fields`	Person data, `residence`, and `property` (primary residence)	1 people credit + 1 property credit when any requested property field is chargeable
`include_properties: true`	Person data, `residence`, and returned associated properties in `properties`	1 people credit + 1 property credit per property returned

The property_count field is free. Property address and location fields (street, unit, city, state, ZIP, latitude, and longitude) are free: when those are the only property fields you request, property is still attached but no property credit is charged. When you combine chargeable property fields with include_properties: true, the primary residence is charged once as part of properties. When property is omitted because the person has no linked properties, no property credit is charged. Only matched results consume credits. Credits are deduplicated within your billing period, so accessing the same entity again is free.

Every response includes a credits object with a full breakdown of what was charged. See Credits for details.

Responses with estimate_cost: true are free and do not include a credits object. The estimate covers people credits. When include_properties is true, it also counts associated properties across all matching people and includes the requested page's property credits in the breakdown.

Notes

Each name object requires a last_name. A name search without a last name would be too broad.
Name matching is case-insensitive and trims whitespace.
The location parameter is optional. When provided, results are scoped to that area. When omitted, the search is nationwide.
You can submit multiple name objects in the data array to search for several people at once.
Use page and per_page to paginate through large result sets. Maximum per_page is 100.
When include_properties is true, each person's properties array includes the person's associated properties, capped for very large portfolios, plus the primary residence when property fields are requested and it falls outside that cap.
Every matched person includes residence with the people credit, so you don't need include_properties or property fields to get a mailing address.
Use estimate_cost: true to preview matching people and, when requested, associated property counts before running a billed enrichment.

Request example

12345678910111213curl -X POST "https://api.v2.dealmachine.com/v1/enrichment/name" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "last_name": "Oster", "first_name": "David" }
    ],
    "location": { "type": "state", "code": "MO" },
    "include_properties": true,
    "fields": ["full_name", "phones", "estimated_value"],
    "per_page": 25,
    "page": 1
  }'

Response example

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647{
  "data": [
    {
      "dm_person_id": "per_x1y2z3",
      "full_name": "David Oster",
      "first_name": "David",
      "last_name": "Oster",
      "phones": [
        { "number": "3145551234", "type": "wireless", "do_not_call": false, "carrier": "Verizon Wireless" },
        { "number": "3145559999", "type": "wireless", "do_not_call": false, "carrier": null }
      ],
      "emails": [{ "address": "david.oster@example.com" }],
      "residence": {
        "address": "1200 Market St",
        "unit": null,
        "city": "St. Louis",
        "state": "MO",
        "zip": "63101",
        "full_address": "1200 Market St, St. Louis, MO 63101"
      },
      "property_count": 1,
      "properties": [
        {
          "dm_property_id": "prop_a1b2c3",
          "address": "1200 Market St",
          "city": "St. Louis",
          "state": "MO",
          "zip": "63101",
          "latitude": 38.627,
          "longitude": -90.1994
        }
      ]
    }
  ],
  "credits": {
    "used": 2,
    "properties": 1,
    "people": 1,
    "deduplicated": 0
  },
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}