Enrich by Email

Look up people by email address. Each item in the data array provides an email, and the API returns all people associated with that address in a contacts array.

Each request accepts up to 250 items in the data array. The response returns every submitted item with a matched flag indicating whether a person was found.

Body Parameters

body dataarrayrequired

Array of email objects to look up (max 250).

Email object properties

body emailstringrequired

Email address to look up (e.g., "john.smith@example.com").

body fieldsstring[]

Field IDs to include in results. Can include both people and property fields. Omit or pass an empty array for the default set.

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) and their always-included fields.

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 a contacts array with every person matching the email address.

Field	Type	Description
`input`	object	Echo of the original input object
`matched`	boolean	`true`
`contacts`	array	All people matching the email address (see below)

Contact Object

Each object in the contacts 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
`properties`	array	Associated properties. Only present when `include_properties` is `true`.
requested fields	varies	Any fields specified in `fields`

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.

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 below)
`match_failure.reason`	string	Human-readable explanation of why no match was found

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 person
`unmatched`	integer	Number of items that did not match

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.

Notes

A single email address may match multiple people. All matching contacts are returned in the contacts array.
Email matching is case-insensitive.
When include_properties is true, each contact'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.
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.

Request example

1234567891011curl -X POST "https://api.v2.dealmachine.com/v1/enrichment/email" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "email": "john.smith@example.com" },
      { "email": "sarah.johnson@example.com" }
    ],
    "fields": ["full_name", "phones", "emails", "estimated_value"],
    "include_properties": true
  }'

Response example

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364{
  "data": [
    {
      "input": {
        "email": "john.smith@example.com"
      },
      "matched": true,
      "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, "carrier": "Verizon Wireless" },
            { "number": "5125559999", "type": "wireless", "do_not_call": false, "carrier": null }
          ],
          "emails": [{ "address": "john.smith@example.com" }],
          "residence": {
            "address": "1200 Barton Springs Rd",
            "unit": null,
            "city": "Austin",
            "state": "TX",
            "zip": "78704",
            "full_address": "1200 Barton Springs Rd, Austin, TX 78704"
          },
          "property_count": 1,
          "properties": [
            {
              "dm_property_id": "prop_a1b2c3",
              "address": "1200 Barton Springs Rd",
              "city": "Austin",
              "state": "TX",
              "zip": "78704",
              "latitude": 30.2598,
              "longitude": -97.7544
            }
          ]
        }
      ]
    },
    {
      "input": {
        "email": "sarah.johnson@example.com"
      },
      "matched": false,
      "match_failure": {
        "code": "not_found",
        "reason": "No person found matching the provided email address"
      }
    }
  ],
  "totals": {
    "submitted": 2,
    "matched": 1,
    "unmatched": 1
  },
  "credits": {
    "used": 2,
    "properties": 1,
    "people": 1,
    "deduplicated": 0
  }
}