Moveandstay API for agents

• Search published properties by country, city, category, capacity and property name.
• Read one property: its description, amenities, the operator's own FAQ, photos and published unit types.
• Send an enquiry — either to a specific property, or to our matching team when no single property is named.

It is not a booking API and there is nothing to reserve. It is not an availability API: we do not hold a live calendar, so no endpoint will tell you whether a property is free on a date. It cannot create or edit listings.

As at 2026-10-05, the directory holds 1,809 published properties across 57 cities in 34 countries. These are point-in-time figures read from the database when this page was generated; they change with every import, so do not cache them.

Every endpoint except the health check needs an API key, sent as a bearer token. There is no anonymous tier: a request without a key is a 401. Ask contact@moveandstay.com for one.

curl -H 'Authorization: Bearer YOUR_KEY' \
  'https://moveandstay.com/api/agent/v1/properties?city=hong-kong&limit=5'

Each key has its own hourly budget — generous for reads, deliberately tight for enquiries. A spent budget answers 429 with a Retry-After header saying when the next slot frees, rather than a flat hour.

An unknown city, country or type is an error, not an empty list. city=hong-kongg answers unknown_city, because returning zero results would tell you we have nothing in Hong Kong.

A capacity filter excludes properties that state no capacity, rather than assuming they fit. Results come back in the same order the website ranks them.

id is the value search returned. The response adds the description, the amenity list, the operator's FAQ, the photos and any published unit types.

No endpoint returns a property's email address or phone number. The enquiry endpoint is how a property is contacted.

Send property_id and the enquiry goes to that property. Leave it out and it goes to our matching team, who contact suitable properties on the traveller's behalf. Both land in the same pipeline a website enquiry lands in.

{
  "property_id": "3f1a2b4c-5d6e-7f80-9a1b-2c3d4e5f6071",
  "contact": {
    "name": "Alice Tan",
    "email": "alice@example.com",
    "phone": "+852 1234 5678"
  },
  "requirements": {
    "move_in_date": "2026-11-01",
    "duration_value": 3,
    "duration_unit": "month",
    "capacity": 2,
    "budget_amount": 40000,
    "budget_currency": "HKD",
    "budget_period": "monthly",
    "message": "Quiet flat, close to the MTR."
  },
  "consent": { "granted": true, "source": "asked in chat" },
  "idempotency_key": "your-unique-id-for-this-enquiry"
}

• consent.granted must be literally true. You are submitting somebody else's contact details to a company that will email them; this is where you confirm they agreed.
• idempotency_key is required. Send the same value if you retry, so a timeout cannot produce a second enquiry. Reusing a key with different content is a 409.
• requirements.capacity is required when property_id is given — the operator is told how many people or desks the enquiry is for, and there is no honest default.

Two success shapes, both 200

{ "status": "RECEIVED",              "enquiry_id": "…", "route": "property" }
{ "status": "RECEIVED_UNDER_REVIEW", "enquiry_id": "…", "route": "concierge" }

RECEIVED means the enquiry entered the pipeline. RECEIVED_UNDER_REVIEW means it has been saved and is being looked at. Tell the person what the status says and nothing more: we do not promise a reply, a response time, or a number of properties that will get in touch.

Every error is { "error": { "code": …, "message": … } }. Branch on code; show message.

Stated plainly, because an agent that knows the edges of a source is more useful than one that guesses at them:

• Availability. We hold no calendar. Nothing here says whether a property is free on a date.
• Minimum stay. We do not store one. Ask the operator through an enquiry.
• Full pricing. Only a "from" rate, exactly as the operator gave it. rate_from: null means *not stated* — not free, and not "ask us".
• Long-stay suitability as a filter. Most properties on the site take stays of a month or more, but we have no stored field for it, so there is no filter to offer.
• Search beyond the name. q matches the property name. To narrow by place, use country, city and type.

• OpenAPI description — the whole surface, for a connector platform or a code generator.
• MCP server — the same three capabilities as MCP tools. Setup at /docs/mcp.
• /llms.txt — what this site is for and when not to use it.
• Every public page also answers to Accept: text/markdown, or a .md suffix.

Questions, or a key: contact@moveandstay.com.