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

# Count People

Returns the total number of people and properties matching a set of filters. Use the same `filters` and `property_match` parameters as [Search People](/api-reference/people/search-people).

## Body Parameters

<ParamField body="locations" type="array">
  Array of [location objects](/concepts/locations) defining where to search. Required unless filters or protocol filters are provided (max 15). Locations use **OR** logic.

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

    <ParamField body="code" type="string">
      Location identifier. Required for `state` (2-letter abbreviation), `county` (5-digit FIPS code), `city` (place ID), and `zip_code` (5-digit ZIP).
    </ParamField>

    <ParamField body="latitude" type="number">
      Center point latitude. Required for `radius`.
    </ParamField>

    <ParamField body="longitude" type="number">
      Center point longitude. Required for `radius`.
    </ParamField>

    <ParamField body="radius_miles" type="number">
      Search radius in miles. Required for `radius`.
    </ParamField>

    <ParamField body="coordinates" type="array">
      Array of `[longitude, latitude]` pairs defining the boundary. Required for `polygon` (minimum 3 points).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="filters" type="array">
  Array of [filter objects](/concepts/filter-values). Required unless locations or protocol filters are provided. You can mix people filters (`source_type=people`) and property filters (`source_type=properties`).

  <Expandable title="Filter object properties">
    <ParamField body="filter_id" type="string" required>
      The filter slug from the [List Filters](/api-reference/filters/list-filters) endpoint (e.g., `has_phone`, `estimated_value`).
    </ParamField>

    <ParamField body="operator" type="string">
      One of the filter's `allowed_operators`. See [Filter Values](/concepts/filter-values) for all operators by type. **Optional for BOOLEAN filters** — automatically defaults to `is_boolean`.
    </ParamField>

    <ParamField body="value" type="any" required>
      The filter value. Shape depends on the operator — can be a number, string, boolean, array, or object. See [Filter Values](/concepts/filter-values).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="include_lists" type="object">
  Restrict counts to people list IDs, for example `{ "people_list_ids": [123] }`.
</ParamField>

<ParamField body="exclude_lists" type="object">
  Exclude people list IDs, for example `{ "people_list_ids": [456] }`.
</ParamField>

<ParamField body="exclude_previously_exported" type="boolean | object">
  Exclude people already exported by your organization.
</ParamField>

<ParamField body="property_match" type="string">
  **Required** when property filters are present. Defines the person-to-property relationship used to connect people to matching properties. Ignored when only people filters are used.

  Options: `owner`, `resident`, `renter`
</ParamField>

***

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.v2.dealmachine.com/v1/people/search/count" \
    -H "Authorization: Bearer dm_sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "locations": [
        { "type": "state", "code": "TX" }
      ],
      "property_match": "owner",
      "filters": [
        {
          "filter_id": "estimated_value",
          "operator": "greater_than",
          "value": 500000
        },
        {
          "filter_id": "has_phone",
          "value": true
        }
      ]
    }'
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.v2.dealmachine.com/v1/people/search/count', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      locations: [{ type: 'state', code: 'TX' }],
      property_match: 'owner',
      filters: [
        {
          filter_id: 'estimated_value',
          operator: 'greater_than',
          value: 500000,
        },
        { filter_id: 'has_phone', value: true },
      ],
    }),
  });

  const counts = await response.json();

  console.log(`People: ${counts.total_people.toLocaleString()}`);
  console.log(`Properties: ${counts.total_properties.toLocaleString()}`);
  ```

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

  response = requests.post(
      "https://api.v2.dealmachine.com/v1/people/search/count",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "locations": [{"type": "state", "code": "TX"}],
          "property_match": "owner",
          "filters": [
              {
                  "filter_id": "estimated_value",
                  "operator": "greater_than",
                  "value": 500000,
              },
              {"filter_id": "has_phone", "value": True},
          ],
      },
  )

  counts = response.json()
  print(f"People: {counts['total_people']:,}")
  print(f"Properties: {counts['total_properties']:,}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 With property filters theme={null}
  {
    "total_people": 412,
    "total_properties": 387,
    "total_results": 412
  }
  ```

  ```json 200 People only (no property filters) theme={null}
  {
    "total_people": 89,
    "total_properties": 0,
    "total_results": 89
  }
  ```

  ```json 400 Validation Error theme={null}
  {
    "error": {
      "code": "validation_error",
      "message": "Validation failed",
      "request_id": "req_abc123def456",
      "details": {
        "issues": [
          {
            "path": "property_match",
            "message": "property_match is required when property filters are present"
          }
        ]
      }
    }
  }
  ```

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

| Field              | Type    | Description                                                                                 |
| ------------------ | ------- | ------------------------------------------------------------------------------------------- |
| `total_people`     | integer | Number of people matching the filters                                                       |
| `total_properties` | integer | Number of properties connected via `property_match`. `0` when no property filters are used. |
| `total_results`    | integer | Always equals `total_people` for people search                                              |

## Notes

* The same filter validation rules apply as [Search People](/api-reference/people/search-people).
* `property_match` is **required** when any property filter is present, and **ignored** when only people filters are used.
* When no property filters are present, `total_properties` is `0`.