# Holland2stay — 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 rental properties across Holland2Stay with access to pricing, availability, location details, and direct booking links. Filter listings by city and availability status to find suitable accommodation in the Netherlands.

**Category:** Real Estate | **Website:** [www.holland2stay.com/residences](https://www.holland2stay.com/residences) | **Docs:** [parse.bot/marketplace/1c0e92be-153e-4053-87dc-5d33aab64748/holland2stay-com-api](https://parse.bot/marketplace/1c0e92be-153e-4053-87dc-5d33aab64748/holland2stay-com-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/holland2stay/`
**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 all listings

Retrieve ALL property listings across all pages by automatically paginating through results. Warning: without filters, this returns ~12,000 listings. Use max_pages to limit the number of pages fetched, or filter by city/availability to reduce the result set. Returns all items in a single array.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `availability` | string | No | Availability filter ID (e.g., '179' for Available to book). Get IDs from get_filters endpoint. |
| `city` | string | No | City filter ID (e.g., '24' for Amsterdam). Get IDs from get_filters endpoint. |
| `max_pages` | integer | No | Maximum number of pages to fetch (0 = all pages). |
| `page_size` | integer | No | Items per API page (max 100). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/holland2stay/get-all-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"availability":"<string>","city":"<string>","max_pages":"<integer>","page_size":"<integer>"}'
```

### Get filters

Get all available filter options for property listings. Returns cities, availability statuses, building names, bedrooms, floor levels, finishing types, residence types, and more with their IDs and display labels. Use these IDs as filter values in get_listings and get_all_listings. Each filter option includes a count of matching listings.

**Estimated cost:** Metered

_No parameters required._

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

### Get listing detail

Get full details for a specific property listing by its URL key (slug). Returns all standard listing fields plus a media gallery of images. The url_key is available from get_listings results (e.g., 'frederik-van-eedenplein-87'). Returns stale_input with kind 'input_not_found' if no listing matches the given url_key.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url_key` | string | Yes | URL key/slug of the listing (e.g., 'frederik-van-eedenplein-87', 'stadsring-161e'). Available from get_listings results. |

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

### Get listings

Retrieve a paginated page of property listings from Holland2Stay. Returns listings with full location details, pricing, availability status, and direct booking URLs. Supports filtering by city and availability status, and sorting by price, name, basic rent, or next contract start date. Each page returns up to 100 items; use the pagination object to navigate through the full catalog of ~12,000 residences.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `availability` | string | No | Availability filter ID (e.g., '179' for Available to book, '336' for Available in lottery). Get IDs from get_filters endpoint. |
| `city` | string | No | City filter ID (e.g., '24' for Amsterdam, '29' for Eindhoven, '6249' for Amersfoort). Get IDs from get_filters endpoint. |
| `page` | integer | No | Page number (1-indexed). |
| `page_size` | integer | No | Number of listings per page (max 100). |
| `sort_by` | string | No | Sort field. Accepted values: 'price', 'name', 'basic_rent', 'next_contract_startdate'. Omitting defaults to 'next_contract_startdate'. |
| `sort_dir` | string | No | Sort direction: 'ASC' or 'DESC'. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/holland2stay/get-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"availability":"<string>","city":"<string>","page":"<integer>","page_size":"<integer>","sort_by":"<string>","sort_dir":"<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.