# Auctionzip — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse auction lots across the AuctionZip marketplace, view detailed lot information and complete auction catalogs, track historical prices realized, and discover auctioneers by name or location. Access auction schedules, item specifications, seller terms, and top-performing auctioneers.

**Category:** Marketplaces | **Website:** [auctionzip.com/](https://auctionzip.com/) | **Docs:** [parse.bot/marketplace/ecb92c6e-6f40-4bfa-bd80-1763391c4a7c/auctionzip-com-api](https://parse.bot/marketplace/ecb92c6e-6f40-4bfa-bd80-1763391c4a7c/auctionzip-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-auctionzip-com-api-ecb92c6e/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_auction_catalog

Retrieve catalog metadata for a specific auction including title, event date, location, seller info, buyer premiums, and bid increments.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `catalog_ref` | string | Yes | The alphanumeric catalog reference, obtainable from get_lot_detail results via itemView.catalogRef |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-auctionzip-com-api-ecb92c6e/get_auction_catalog \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog_ref":"<string>"}'
```

### get_auction_details

Get terms, shipping, payment details, and bidding increments for an auction catalog. Complements get_auction_catalog with the full terms-of-sale text and fee structure.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `catalog_ref` | string | Yes | The alphanumeric catalog reference, obtainable from get_lot_detail results via itemView.catalogRef |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-auctionzip-com-api-ecb92c6e/get_auction_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog_ref":"<string>"}'
```

### get_lot_detail

Fetch full metadata for a single auction lot by its 10-character alphanumeric reference. Returns pricing, photos, estimates, condition, catalog reference, and bid status.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lot_ref` | string | Yes | The unique 10-character alphanumeric lot reference, obtainable from search_lots results |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-auctionzip-com-api-ecb92c6e/get_lot_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lot_ref":"<string>"}'
```

### get_prices_realized

Look up historical sold prices for items matching keywords. Returns up to 20 price records per request with item titles and final sale prices.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | integer | No | Category ID filter. 0 returns all categories. |
| `keywords` | string | Yes | Search keywords for historical price lookup |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-auctionzip-com-api-ecb92c6e/get_prices_realized \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<integer>","keywords":"<string>"}'
```

### get_top_auctioneers

Retrieve this week top 10 most viewed auctioneers from AuctionZip, including rank, name, location, and phone number.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-auctionzip-com-api-ecb92c6e/get_top_auctioneers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_auctioneers

Search for auctioneers by company name or last name. Returns matching auctioneer names with profile URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Company name or last name keyword to search for |
| `zip` | string | No | ZIP code for proximity-based search |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-auctionzip-com-api-ecb92c6e/search_auctioneers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>","zip":"<string>"}'
```

### search_auctions

Browse the auction calendar. Without a day parameter, returns a monthly calendar view showing auction counts per day. With a day parameter, returns a list of auctions scheduled for that specific day.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `day` | string | No | Day of month (1-31). When provided, returns list of auctions for that specific day instead of calendar view. |
| `keywords` | string | No | Search keywords to filter auctions |
| `month` | string | No | Month number (1-12). Omitting defaults to current month. |
| `year` | string | No | Four-digit year. Omitting defaults to current year. |
| `zip` | string | No | ZIP code for proximity-based search |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-auctionzip-com-api-ecb92c6e/search_auctions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"day":"<string>","keywords":"<string>","month":"<string>","year":"<string>","zip":"<string>"}'
```

### search_lots

Full-text search over online bidding lots. Returns paginated results with lot references, titles, and URLs. Each lot_ref can be passed to get_lot_detail for full metadata.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for paginated results |
| `query` | string | Yes | Search keyword for lot titles |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-auctionzip-com-api-ecb92c6e/search_lots \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```