---
title: "Radius Search"
method: POST
path: "/mailing-lists-utils/buy-radius-search"
tags: ["Mailing Lists"]
---

# Radius Search

`POST /mailing-lists-utils/buy-radius-search`

## Request

- Base URL: `https://api.thanks.io/api/v2`
- URL: `https://api.thanks.io/api/v2/mailing-lists-utils/buy-radius-search`
- Auth: HTTP bearer

This call will purchase a radius search mailing listing and add it to your account. Each record added to the mailing list costs $.05. You can specify the number of records to return (up to 2,500) and the address/postal code to center the search around. You can also specify a mailing_list_id to add the results to an existing mailing list, or leave it blank to create a new mailing list. While API/Zapier Test Mode is enabled on the account, this endpoint is limited to 5 records per purchase — test mode cancels orders, but buying a radius search is not an order and is charged in full, so the limit is what keeps an integration under development from buying a full list by accident.

## Request body

- object
  - `mailing_list_id` integer: ID of the mailing list to add the radius search results to. If not provided, a new mailing list will be created.
  - `address` string, required: Street address to use for center of nearest neighbor search.
  - `postal_code` string, required: Postal code to use for center of nearest neighbor search.
  - `record_count` integer, required: Number of nearest neighbors to search for. While API/Zapier Test Mode is enabled on the account, a purchase through this endpoint is limited to 5 records; a larger value is refused with a 422 and nothing is bought or charged. Buying from the dashboard is not affected and keeps the full 2,500.
  - `record_types` 'all' | 'likelytomove' | 'apartmentcomplex' | 'likelytodownsize' | 'likelytorefi' | 'absenteeowner' | 'highnetworth' | 'majorityhomeequity' | 'homefreeclear' | 'underwater' | 'kidsinhousehold' | 'newhomeowner' | 'firsttimehomebuyer' | 'renters' | 'retiring' | 'retired' | 'pool' | 'onlybusinesses' | 'newbusiness': Which type of records to search for
  - `include_condos` boolean: Include condos in search.
  - `append_data` boolean: Append phone and email to each record for an additional fee ($.20 per record).
  - `use_property_owner` boolean: Use Property Owners Address when searching for a commercial record_type.
  - `include_search_address` boolean: Specifies whether to include the search address in the mailing list created.

## Response `200`

Successful Response

- object
  - `message` string
  - `mailing_list_id` integer
  - `failure` boolean

## Other responses

- `400`: Bad Request
- `403`: Access token is missing or invalid
- `404`: Resource not found
- `409`: Duplicate radius search purchase. An identical purchase was already made from this account within the last 24 hours and was refused so the records are not bought twice. The response carries the identifiers the original purchase produced, so use those instead of retrying. Change any search parameter, or wait for the window to pass, to buy again.
- `422`: Record count above the API/Zapier Test Mode limit. While test mode is enabled on the account, a purchase through this endpoint is limited to 5 records. The request is refused during validation, so no leads are bought, the account is not charged, and the 24 hour duplicate purchase window is not used up. Send a record_count of 5 or fewer, or turn off API/Zapier Test Mode in API Settings to buy a full list.

## Changes

- **2026-09-24** `63c911a0e3c5`: 3 info
  - the `include_condos` request property default value changed from `false` to `true`
  - added the new `apartmentcomplex` enum value to the request property `record_types`
  - added the new `likelytodownsize` enum value to the request property `record_types`
- **2026-09-09** `1c53bf447639`: 1 info
  - added the non-success response with the status `422`
- **2026-09-09** `f51ce18e6297`: 1 breaking, 1 info
  - the `record_count` request property's max was decreased to `2500.00`
  - added the non-success response with the status `409`
- **2026-02-12** `376769ca2192`: 1 info
  - added the new optional request property `include_search_address`
- **2025-10-17** `529a5adc09d5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/thanks-io/apis/thanks-io-api/changes/mailing-lists-utils/buy-radius-search/post.md)

---

[API](https://skmtc.dev/thanks-io/apis/thanks-io-api.md) · [All operations](https://skmtc.dev/thanks-io/apis/thanks-io-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thanks-io/apis/thanks-io-api/revisions/c403fbf3dc0f?raw)