# Subito — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 listings on Subito.it, Italy's leading classifieds marketplace. Filter by keyword, category, location, and price. Retrieve listing details, real estate listings, dealer inventories, and seller contact information.

**Category:** Marketplaces | **Website:** [subito.it/](https://subito.it/) | **Docs:** [parse.bot/marketplace/01b8d429-40aa-4b9d-9645-d2701e278bdb/subito-it-api](https://parse.bot/marketplace/01b8d429-40aa-4b9d-9645-d2701e278bdb/subito-it-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/subito/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get categories

Get the full category and sub-category tree for Subito.it. Each category has a key (ID), value (display name), friendly_name (URL slug), weight (sort order), and optional macrocategory_id indicating its parent macro-category. Top-level entries without macrocategory_id are macro-categories themselves.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/subito/get-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get dealer listings

Fetch all listings from a specific advertiser/dealer by their user ID. Returns paginated results. The user_id can be found in search results or listing details under the advertiser object.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results to return per page. |
| `offset` | integer | No | Pagination offset (start index). |
| `user_id` | string | Yes | The advertiser's numeric user ID (found in search results or listing details under advertiser.user_id). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/subito/get-dealer-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","user_id":"<string>"}'
```

### Get listing details

Get full details for a single listing by its numeric ID. Returns the complete listing object including description, all images, all features (price, condition, shipping), advertiser info, and location. The ad_id can be a numeric listing ID (from the end of listing URLs) or a full URN from search results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ad_id` | string | Yes | Numeric listing ID (found at the end of listing URLs) or a full listing URN. If a URN is passed, the numeric ID is extracted automatically. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/subito/get-listing-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ad_id":"<string>"}'
```

### Get real estate listings

Fetch real estate listings with optional sub-category, location, and price filters. Defaults to the Real Estate macro-category (ID 6). Returns paginated results sorted by recency.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Real estate category or sub-category ID: '6' (all Real Estate), '7' (Appartamenti), '29' (Ville), '30' (Terreni), '31' (Garage e box), '32' (Loft/mansarde), '33' (Case vacanza), '8' (Uffici e Locali commerciali), '43' (Camere/Posti letto). |
| `city` | string | No | City/Provincia ID (numeric). |
| `limit` | integer | No | Number of results to return per page. |
| `listing_type` | string | No | Listing type: 's' for sale, 'a' for rent. |
| `offset` | integer | No | Pagination offset (start index). |
| `price_max` | string | No | Maximum price filter (numeric string). |
| `price_min` | string | No | Minimum price filter (numeric string). |
| `region` | string | No | Region ID (numeric). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/subito/get-real-estate-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","city":"<string>","limit":"<integer>","listing_type":"<string>","offset":"<integer>","price_max":"<string>","price_min":"<string>","region":"<string>"}'
```

### Get seller phone

Reveal the seller's phone number for a specific listing using its URN. Not all listings have phone numbers — private sellers often omit them; business/dealer listings typically include one. Returns stale_input when no phone is available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `urn` | string | Yes | The listing URN (e.g. 'id:ad:db386d21-15cd-40a0-9032-b7349f725010:list:649692973'), found in search_listings or get_listing_details results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/subito/get-seller-phone \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"urn":"<string>"}'
```

### Search listings

Search for listings on Subito.it with various filters including keyword, category, location, and price range. Returns paginated results sorted by recency. At least one filter (query, category, region, city) is recommended to narrow results; calling with no filters returns all listings site-wide.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `advertiser_type` | string | No | Advertiser type: '0' for private, '1' for business. |
| `category` | string | No | Category ID (e.g. '6' for Real Estate, '2' for Cars, '12' for Telefonia). Use get_categories to discover all IDs. |
| `city` | string | No | City/Provincia ID (numeric). |
| `limit` | integer | No | Number of results to return per page. |
| `listing_type` | string | No | Listing type: 's' for sale (vendita), 'a' for rent (affitto). |
| `offset` | integer | No | Pagination offset (start index). |
| `price_max` | string | No | Maximum price filter (numeric string). |
| `price_min` | string | No | Minimum price filter (numeric string). |
| `query` | string | No | Search keyword. |
| `region` | string | No | Region ID (numeric). |
| `town` | string | No | Town/Comune ID (numeric ISTAT code). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/subito/search-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_type":"<string>","category":"<string>","city":"<string>","limit":"<integer>","listing_type":"<string>","offset":"<integer>","price_max":"<string>","price_min":"<string>","query":"<string>","region":"<string>","town":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.