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

# Get Person

Retrieve a single person by their DealMachine person ID. Returns contact information including name, phone numbers, email addresses, and demographic data.

## Path Parameters

<ParamField path="id" type="string" required>
  DealMachine person ID (e.g., `per_12345`).
</ParamField>

## Query Parameters

<ParamField query="enrich" type="boolean" default={true}>
  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. Set `false` for preview mode with base fields only. Preview mode omits phones, emails, and demographic data and consumes no credits.
</ParamField>

<ParamField query="include_properties" type="boolean" default={false}>
  When `true`, includes the person's associated properties with address, valuation, and ownership
  data.
</ParamField>

<ParamField query="property_limit" type="integer" default={20}>
  Maximum associated properties to return when `include_properties=true`. Maximum: 100.
</ParamField>

<ParamField query="fields" type="string">
  Comma-separated field IDs from [List Fields](/api-reference/fields/list-fields). People fields return on the person. Property fields return under `property`. Requires `enrich=true`.
</ParamField>

***

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.v2.dealmachine.com/v1/people/per_12345?include_properties=true&property_limit=20&fields=estimated_household_income,estimated_value" \
    -H "Authorization: Bearer dm_sk_live_xxx"
  ```

  ```typescript Node.js theme={null}
  const response = await fetch(
    'https://api.v2.dealmachine.com/v1/people/per_12345?include_properties=true&property_limit=20&fields=estimated_household_income,estimated_value',
    {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    }
  );

  const { data } = await response.json();
  console.log(`${data.full_name} — ${data.phones?.[0]?.number}`);

  if (data.properties) {
    for (const prop of data.properties) {
      console.log(`  Property: ${prop.address}, ${prop.city} ${prop.state}`);
    }
  }
  ```

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

  response = requests.get(
      "https://api.v2.dealmachine.com/v1/people/per_12345",
      headers={"Authorization": f"Bearer {api_key}"},
      params={
          "include_properties": "true",
          "property_limit": 20,
          "fields": "estimated_household_income,estimated_value",
      },
  )

  data = response.json()["data"]
  print(f"{data['full_name']} — {data.get('phones', [{}])[0].get('number', 'N/A')}")
  for prop in data.get("properties", []):
      print(f"  Property: {prop['address']}, {prop['city']} {prop['state']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "dm_person_id": "per_12345",
      "full_name": "John Smith",
      "first_name": "John",
      "last_name": "Smith",
      "middle_initial": "R",
      "person_age": 45,
      "estimated_household_income": 125000,
      "phones": [
        { "number": "5125551234", "type": "wireless", "do_not_call": false },
        { "number": "5125559999", "type": "wireless", "do_not_call": false }
      ],
      "emails": [{ "address": "john.smith@example.com" }],
      "properties": [
        {
          "dm_property_id": "prop_67890",
          "full_address": "1200 Barton Springs Rd, Austin, TX 78704",
          "address": "1200 Barton Springs Rd",
          "city": "Austin",
          "state": "TX",
          "zip": "78704",
          "latitude": 30.2598,
          "longitude": -97.7544,
          "estimated_value": 575000,
          "estimated_equity_amount": 414000,
          "estimated_equity_percentage": 72,
          "year_built": 1985,
          "living_area_sqft": 2200,
          "lot_size_sqft": 8500,
          "num_bedrooms": 4,
          "num_bathrooms": 2,
          "num_stories": 2,
          "owner_occupied": true,
          "last_sale_date": "2018-06-15",
          "last_sale_amount": 380000,
          "total_assessed_value": 520000,
          "annual_property_tax_amount": 11440,
          "num_mortgages": 1,
          "total_original_loan_amount": 304000,
          "total_estimated_loan_balance": 161000,
          "apn": "0123456789",
          "fips": "48453",
          "is_likely_owner": true,
          "is_resident": true,
          "is_likely_renter": false
        }
      ]
    },
    "credits": {
      "used": 2,
      "properties": 1,
      "people": 1,
      "deduplicated": 0
    }
  }
  ```

  ```json 400 Invalid ID theme={null}
  {
    "error": {
      "code": "invalid_person_id",
      "message": "Invalid person ID format. Expected format: per_12345",
      "request_id": "req_abc123"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": {
      "code": "person_not_found",
      "message": "No person found with ID per_99999",
      "request_id": "req_abc123"
    }
  }
  ```
</ResponseExample>

## Response Fields

| Field                        | Type   | Description                                                                                      |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `dm_person_id`               | string | DealMachine person ID                                                                            |
| `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 (e.g., `"Bachelor's Degree"`)                                                    |
| `occupation`                 | string | Occupation                                                                                       |
| `occupation_group`           | string | Occupation group                                                                                 |
| `language`                   | string | Primary language                                                                                 |
| `net_asset_value`            | string | Net asset value range                                                                            |
| `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=true`. Limited by `property_limit`. |

### Property Fields (when included)

| Field                                          | Type    | Description                             |
| ---------------------------------------------- | ------- | --------------------------------------- |
| `dm_property_id`                               | string  | DealMachine property ID                 |
| `full_address`                                 | string  | Complete formatted address              |
| `address`, `address_2`, `city`, `state`, `zip` | string  | Parsed address components               |
| `latitude`, `longitude`                        | number  | Coordinates                             |
| `estimated_value`                              | number  | Estimated market value                  |
| `estimated_equity_amount`                      | number  | Estimated equity in dollars             |
| `estimated_equity_percentage`                  | number  | Estimated equity as percentage          |
| `year_built`                                   | number  | Year the property was built             |
| `living_area_sqft`                             | number  | Interior living area in square feet     |
| `lot_size_sqft`                                | number  | Total lot size in square feet           |
| `num_bedrooms`                                 | number  | Number of bedrooms                      |
| `num_bathrooms`                                | number  | Number of bathrooms                     |
| `num_stories`                                  | number  | Number of stories                       |
| `property_use_code_id`                         | number  | Property use code                       |
| `owner_occupied`                               | boolean | Whether the owner lives at the property |
| `last_sale_date`                               | string  | Date of last sale                       |
| `last_sale_amount`                             | number  | Price of last sale                      |
| `total_assessed_value`                         | number  | Tax assessor's total assessed value     |
| `annual_property_tax_amount`                   | number  | Annual property tax amount              |
| `num_mortgages`                                | number  | Number of active mortgages              |
| `total_original_loan_amount`                   | number  | Total original loan amount              |
| `total_estimated_loan_balance`                 | number  | Total estimated remaining loan balance  |
| `apn`                                          | string  | Assessor's Parcel Number                |
| `fips`                                         | string  | 5-digit FIPS county code                |
| `is_likely_owner`                              | boolean | Whether person is likely the owner      |
| `is_resident`                                  | boolean | Whether person is a resident            |
| `is_likely_renter`                             | boolean | Whether person is likely a renter       |

## Credits

When `enrich=true` (the default), this endpoint consumes 1 [people credit](/concepts/credits) for the person. When `include_properties=true`, included properties consume property credits. Chargeable property fields requested through `fields` add a property credit. Credits are deduplicated within your billing period, so looking up the same person or property again is free.

When `enrich=false`, no credits are consumed. Only base fields are returned (name, match flags). No phones, emails, or demographic data is included.