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

# Export People

Export matching people as a compressed CSV file. Returns signed download URLs that you can use to download the exported data. This endpoint is designed for bulk data extraction — up to **1,000,000 records** per export.

<Warning>
  This is a **synchronous, long-running endpoint**. The response is returned once the entire export
  is complete, which typically takes **up to 30 seconds**. Set your HTTP client timeout to at least
  **120 seconds** to avoid premature disconnects. See the [Exporting Guide](/concepts/exporting) for
  best practices.
</Warning>

## Body Parameters

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

  <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, e.g., `"TX"`), `county` (5-digit FIPS code, e.g., `"29189"`), `city` (place ID, e.g., `"7333"`), and `zip_code` (5-digit ZIP, e.g., `"63101"`).
    </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="include_lists" type="object">
  Export only 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="filters" type="array">
  Array of [filter objects](/concepts/filter-values). Omit or pass an empty array to export with no filters (location-only).

  <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`, `age`).
    </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="fields" type="string[]">
  [Field IDs](/concepts/fields) to include in the CSV columns. Omit or pass an empty array for the
  default set.
</ParamField>

<ParamField body="property_match" type="string">
  Defines the person-to-property relationship for the export.

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

<ParamField body="anchor" type="string" default="person">
  Controls what each CSV row represents. Use `person` for one row per person (default), `phone` for one row per phone number, or `email` for one row per email address.
</ParamField>

<ParamField body="require_phone" type="boolean">
  Only include records where the contact has a phone number. Useful for telemarketing or outreach
  campaigns.
</ParamField>

<ParamField body="require_email" type="boolean">
  Only include records where the contact has an email address. Useful for email marketing campaigns.
</ParamField>

<ParamField body="mobile_only" type="boolean">
  Only include wireless phone numbers. Cannot be combined with `landline_only`.
</ParamField>

<ParamField body="landline_only" type="boolean">
  Only include landline phone numbers. Cannot be combined with `mobile_only`.
</ParamField>

<ParamField body="scrub_dnc" type="boolean">
  Exclude contacts on the Do Not Call registry. Recommended for compliance with telemarketing
  regulations.
</ParamField>

***

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.v2.dealmachine.com/v1/people/export" \
    -H "Authorization: Bearer dm_sk_live_xxx" \
    -H "Content-Type: application/json" \
    --max-time 120 \
    -d '{
      "locations": [
        { "type": "state", "code": "CA" }
      ],
      "filters": [
        {
          "filter_id": "has_phone",
          "value": true
        }
      ],
      "fields": [
        "full_name",
        "phones",
        "emails"
      ],
      "property_match": "owner"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "export_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "record_count": 8234,
    "file_count": 1,
    "total_file_size": 1843200,
    "execution_time": 28.3,
    "download_urls": [
      {
        "filename": "people_export_2026-02-17.csv.gz",
        "url": "https://storage.googleapis.com/...",
        "size": 1843200
      }
    ],
    "credits": {
      "used": 8234,
      "people": 8234
    }
  }
  ```

  ```json 400 No Records theme={null}
  {
    "error": {
      "code": "invalid_request",
      "message": "No records match your filters"
    }
  }
  ```

  ```json 400 Too Many Records theme={null}
  {
    "error": {
      "code": "invalid_request",
      "message": "Export limited to 1,000,000 records. Your query matches 2,000,000 records. Narrow your filters to reduce results.",
      "details": {
        "record_count": 2000000,
        "limit": 1000000
      }
    }
  }
  ```

  ```json 429 Credit Limit theme={null}
  {
    "error": {
      "code": "export_limit_exceeded",
      "message": "Export limit reached"
    }
  }
  ```

  ```json 429 Export In Progress theme={null}
  {
    "error": {
      "code": "export_in_progress",
      "message": "An export is already in progress for your organization. Please wait for it to complete before starting another."
    }
  }
  ```
</ResponseExample>

## Response

| Field             | Type    | Description                                                          |
| ----------------- | ------- | -------------------------------------------------------------------- |
| `export_id`       | string  | Unique identifier for this export                                    |
| `record_count`    | integer | Number of records in the exported CSV                                |
| `file_count`      | integer | Number of files generated (large exports may produce multiple files) |
| `total_file_size` | integer | Total size of all files in bytes                                     |
| `execution_time`  | number  | Time taken to complete the export in seconds                         |
| `download_urls`   | array   | Signed download URLs for the exported files                          |
| `credits.used`    | integer | Total credits consumed by this export                                |
| `credits.people`  | integer | Number of people lead records exported                               |

<Note>
  People, phone, and email exports from Find People charge people data credits per distinct contact.
  Associated properties included in the output consume property credits.
</Note>

### `download_urls`

Each object in the `download_urls` array contains:

| Field      | Type    | Description                                                                            |
| ---------- | ------- | -------------------------------------------------------------------------------------- |
| `filename` | string  | Suggested filename for the download (e.g., `people_export_2026-02-17.csv.gz`)          |
| `url`      | string  | Signed URL — valid for a limited time. Download promptly after receiving the response. |
| `size`     | integer | File size in bytes                                                                     |

<Note>
  Exported files are **gzip-compressed CSV** (`.csv.gz`). Most tools (Excel, Google Sheets, Python
  pandas) can open `.csv.gz` files directly. To decompress manually, use `gunzip` or any archive
  tool.
</Note>

***

## Tips

* Use the [Count People](/api-reference/people/count-people) endpoint first to check how many records match your filters before committing to an export.
* For datasets under 250 records, the paginated [Search People](/api-reference/people/search-people) endpoint may be more appropriate.
* People exports are **deduplicated** — each unique person appears only once in the CSV, even if they match multiple properties.
* Use the `export_id` in the response with [Get Export](/api-reference/exports/get-export) to retrieve download URLs later, or [List Exports](/api-reference/exports/list-exports) to browse past exports.
* See the [Exporting Guide](/concepts/exporting) for timeout configuration, download handling, and best practices.