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

Look up people by phone number. Each item in the `data` array provides a `phone` number, and the API returns all people associated with that number in a `contacts` array.

<Note>
  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.
</Note>

## Body Parameters

<ParamField body="data" type="array" required>
  Array of phone objects to look up (max 250).

  <Expandable title="Phone object properties">
    <ParamField body="phone" type="string" required>
      Phone number (10-digit US number, e.g., `"5125551234"`). The API normalizes common formats — dashes, spaces, parentheses, and the `+1` country code are all accepted.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fields" type="string[]">
  [Field IDs](/concepts/fields) to include in results. Can include both people and property fields.
  Omit or pass an empty array for the default set.
</ParamField>

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

***

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.v2.dealmachine.com/v1/enrichment/phone" \
    -H "Authorization: Bearer dm_sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "data": [
        { "phone": "5125551234" },
        { "phone": "2145559876" }
      ],
      "fields": ["full_name", "phones", "emails", "estimated_value"],
      "include_properties": true
    }'
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.v2.dealmachine.com/v1/enrichment/phone', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: [{ phone: '5125551234' }, { phone: '2145559876' }],
      fields: ['full_name', 'phones', 'emails', 'estimated_value'],
      include_properties: true,
    }),
  });

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

  console.log(`Matched ${totals.matched} of ${totals.submitted}`);
  for (const item of data) {
    if (item.matched) {
      for (const contact of item.contacts) {
        console.log(`${item.input.phone} → ${contact.full_name}`);
        for (const prop of contact.properties ?? []) {
          console.log(`  Property: ${prop.address}`);
        }
      }
    } else {
      console.log(`No match: ${item.input.phone}`);
    }
  }
  ```

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

  response = requests.post(
      "https://api.v2.dealmachine.com/v1/enrichment/phone",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "data": [
              {"phone": "5125551234"},
              {"phone": "2145559876"},
          ],
          "fields": ["full_name", "phones", "emails", "estimated_value"],
          "include_properties": True,
      },
  )

  body = response.json()
  for item in body["data"]:
      if item["matched"]:
          for contact in item["contacts"]:
              print(f"{item['input']['phone']} → {contact['full_name']}")
              for prop in contact.get("properties", []):
                  print(f"  Property: {prop['address']}")
      else:
          print(f"No match: {item['input']['phone']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "input": {
          "phone": "5125551234"
        },
        "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 },
              { "number": "5125559999", "type": "wireless", "do_not_call": false }
            ],
            "emails": [{ "address": "john.smith@example.com" }],
            "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
              }
            ]
          },
          {
            "dm_person_id": "per_a4b5c6",
            "full_name": "Jane Smith",
            "first_name": "Jane",
            "last_name": "Smith",
            "phones": [{ "number": "5125551234", "type": "wireless", "do_not_call": false }],
            "emails": [{ "address": "jane.smith@example.com" }],
            "property_count": 0
          }
        ]
      },
      {
        "input": {
          "phone": "2145559876"
        },
        "matched": false,
        "match_failure": {
          "code": "not_found",
          "reason": "No person found matching the provided phone number"
        }
      }
    ],
    "totals": {
      "submitted": 2,
      "matched": 1,
      "unmatched": 1
    },
    "credits": {
      "used": 3,
      "properties": 1,
      "people": 2,
      "deduplicated": 0
    }
  }
  ```

  ```json 400 Validation Error theme={null}
  {
    "error": {
      "code": "validation_error",
      "message": "Validation failed",
      "request_id": "req_abc123def456",
      "details": {
        "issues": [
          {
            "path": "data[0].phone",
            "message": "phone must be a valid 10-digit US phone number"
          }
        ]
      }
    }
  }
  ```

  ```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 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 phone number.

| Field      | Type    | Description                                      |
| ---------- | ------- | ------------------------------------------------ |
| `input`    | object  | Echo of the original input object                |
| `matched`  | boolean | `true`                                           |
| `contacts` | array   | All people matching the phone number (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.                        |
| `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                                                                      |
| `properties`              | array          | Associated properties. Only present when `include_properties` is `true`.             |
| *requested fields*        | varies         | Any fields specified in `fields`                                                     |

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

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.

## Notes

* A single phone number may match multiple people. All matching contacts are returned in the `contacts` array.
* Phone numbers are normalized to 10 digits. Formatting like `(512) 555-1234`, `512-555-1234`, `+1 512 555 1234` are all accepted and matched against the same canonical number.
* When `include_properties` is `true`, each contact's `properties` array includes all associated properties.
* 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.