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

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

<Note>
  This endpoint returns **paginated results**: up to 100 people per page. Use `page` and `per_page`
  to navigate through large result sets.
</Note>

## Body Parameters

<ParamField body="data" type="array" required>
  Array of name objects to search for (max 250). Each object must include a `last_name`.

  <Expandable title="Name object properties">
    <ParamField body="last_name" type="string" required>
      Last name to search for (case-insensitive).
    </ParamField>

    <ParamField body="first_name" type="string">
      First name to narrow results (case-insensitive). Omit to return all people with the matching last name.
    </ParamField>

    <ParamField body="middle_initial" type="string">
      Single-character middle initial to narrow results (case-insensitive).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="location" type="object">
  Location to narrow results to a specific area. When omitted, results are not filtered by location.

  <Expandable title="Location object properties">
    <ParamField body="type" type="string" required>
      Location type: `"state"`, `"zip_code"`, or `"county"`.
    </ParamField>

    <ParamField body="code" type="string" required>
      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"`).
    </ParamField>
  </Expandable>
</ParamField>

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

<ParamField body="fields" type="string[]">
  [Field IDs](/concepts/fields) to include in results. People fields return on each person. Property fields return under `property`.
</ParamField>

<ParamField body="page" type="integer" default={1}>
  Page number for pagination (starts at 1).
</ParamField>

<ParamField body="per_page" type="integer" default={25}>
  Number of results per page (max 100).
</ParamField>

<ParamField body="estimate_cost" type="boolean" default={false}>
  When `true`, returns a match count and credit estimate without returning person data or consuming
  credits.
</ParamField>

***

<RequestExample>
  ```bash cURL theme={null}
  curl -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
    }'
  ```

  ```bash Estimate Cost theme={null}
  curl -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" },
      "estimate_cost": true,
      "per_page": 25,
      "page": 1
    }'
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.v2.dealmachine.com/v1/enrichment/name', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      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,
    }),
  });

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

  console.log(`Found ${pagination.total} results (page ${pagination.page})`);
  for (const contact of data) {
    console.log(`${contact.full_name} - ${contact.phones?.[0]?.number}`);
    for (const prop of contact.properties ?? []) {
      console.log(`  Property: ${prop.address}`);
    }
  }
  ```

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

  response = requests.post(
      "https://api.v2.dealmachine.com/v1/enrichment/name",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "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,
      },
  )

  body = response.json()
  print(f"Found {body['pagination']['total']} results")
  for contact in body["data"]:
      print(f"{contact['full_name']} - {contact.get('phones', [{}])[0].get('number')}")
      for prop in contact.get("properties", []):
          print(f"  Property: {prop['address']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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 },
          { "number": "3145559999", "type": "wireless", "do_not_call": false }
        ],
        "emails": [{ "address": "david.oster@example.com" }],
        "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
    }
  }
  ```

  ```json Cost Estimate theme={null}
  {
    "totals": {
      "people": 412,
      "properties": 623
    },
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total_results": 412,
      "total_pages": 17,
      "has_next_page": true,
      "has_previous_page": false
    },
    "estimated_credits": {
      "this_page": 63,
      "total_all_pages": 1035,
      "breakdown": {
        "people": 25,
        "properties": 38,
        "already_accessed": 0,
        "note": "Estimate includes people and associated property credits. Actual credits may be lower due to active licenses and deduplication within your billing period."
      }
    }
  }
  ```

  ```json 400 Validation Error theme={null}
  {
    "error": {
      "code": "validation_error",
      "message": "Validation failed",
      "request_id": "req_abc123def456",
      "details": {
        "issues": [
          {
            "path": "data",
            "message": "Required"
          }
        ]
      }
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "invalid_api_key",
      "message": "The provided API key is invalid",
      "request_id": "req_def456ghi789"
    }
  }
  ```

  ```json 429 Rate Limited theme={null}
  {
    "error": {
      "code": "rate_limit_exceeded",
      "message": "Too many requests. Please retry after the specified time.",
      "request_id": "req_ghi789jkl012"
    }
  }
  ```
</ResponseExample>

## 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.                        |
| `property`                | object         | Property context and requested property fields when `fields` includes property data. |
| `phones`                  | array          | Phone numbers with `number`, normalized `type`, and `do_not_call`                    |
| `emails`                  | array          | Email addresses with `address`                                                       |
| `properties`              | array          | Associated properties. Only present when `include_properties` is `true`.             |

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

This endpoint consumes 1 [people credit](/concepts/credits) per matched person. The `property_count` field is free. When `include_properties` is `true`, included properties consume property credits. Chargeable property fields requested through `fields` add property credits. 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](/concepts/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 all associated properties.
* Use `estimate_cost: true` to preview matching people and, when requested, associated property
  counts before running a billed enrichment.