Developer guide

Vacancies Syndication API

Expose your own live room/property vacancies on your own website, CRM or portal — the same read-only feed that powers brand sites. The feed is scoped to your organisation by your API key: you only ever serve your vacancies. It contains no personal data— only the advert content you've published (title, price, photos, availability, enquiry link).

1. Get your API key

Your key is a secret — treat it like a password. Generate and manage keys in the SmartTenant admin under Settings → API & integrations → Vacancy syndication.

Generate key — the full value is shown once at creation, so copy it then.
Labeleach key (e.g. "Main website", "Staging") so you can tell them apart.
Revoke a key any time; revoked keys stop working immediately.

Manage your API keys

A vacancy only appears in the feed once it's advert-ready: marked to advertise on brand sites and it has at least one photo. Build the advert in Vacancies → Adverts to build first.

2. Authentication

Send your key in the x-syndication-key request header on every call:

x-syndication-key: st_synd_xxxxxxxxxxxxxxxxxxxxxxxx

A missing or invalid/revoked key returns 401 Unauthorized.
The key both authenticates you and scopes the response to your organisation — there is no account id to pass.
Call the API server-to-server.Don't put the key in browser code. Fetch from your backend (or a build step / serverless function) and render or cache it on your server.

3. Endpoints

Base URL:

https://www.smarttenant.co.uk/api/public/listings

List vacancies — `GET /api/public/listings`

Query parameters (all optional):

Param	Type	Notes
`available`	boolean	Defaults `true` — only currently-available vacancies.
`limit`	integer	1–100. Caps the number returned.
`city`	string	Case-insensitive city match.
`area`	string	Filter by area/locality.

Get one vacancy — `GET /api/public/listings/{id}`

{id} is the listing id from the list response. Returns a single listing, or 404 Not Foundif it isn't available (or isn't yours).

4. Examples

cURL

curl -s "https://www.smarttenant.co.uk/api/public/listings?available=true&limit=50" \
  -H "x-syndication-key: $SMARTTENANT_SYNDICATION_KEY"

Node / server-side fetch

const res = await fetch(
  "https://www.smarttenant.co.uk/api/public/listings?available=true",
  { headers: { "x-syndication-key": process.env.SMARTTENANT_SYNDICATION_KEY } },
);
if (!res.ok) throw new Error(`Syndication feed ${res.status}`);
const { listings } = await res.json();
// render `listings` into your page / cache them

5. Limits, caching & CORS

Rate limit: 120 requests/minute per key (429 if exceeded).
Caching: responses send Cache-Control: public, max-age=120. The feed changes slowly — cache it your side and refresh every few minutes.
CORS:designed for server-to-server use. Browser (cross-origin) calls are only permitted from origins you've allow-listed with us.

6. Support

Questions or need an origin allow-listed: [email protected].