Listings API

Use the Listings API to read the listings and media syndicated to one active site. It is read-only: updates enter FeedSync through a configured feed, the dashboard, or the REAXML Upload API.

The Listings OpenAPI reference is the contract for parameters, schemas, authentication, and status codes. This guide explains the behavior needed to build a reliable importer.

Requirements

You need the site's UUID and a site-bound API key containing listings:read. The production base URL is:

https://feedsync.com.au/api/v1

Send the key as a Bearer token or as X-API-Key:

curl "https://feedsync.com.au/api/v1/sites/SITE_UUID/listings" \
  --header "Authorization: Bearer fs_your_api_key" \
  --header "Accept: application/json"

The key can access only its configured site. The site must be active and have a feed attached. Every listing and media operation below requires listings:read.

Endpoints

Method	Path	Purpose
`GET`	`/sites/{site}/listings`	Filter, sort, project, and paginate listings.
`GET`	`/sites/{site}/listings/fields`	Discover fields accepted by `fields`.
`GET`	`/sites/{site}/listings/search`	Address, location, and radius search.
`GET`	`/sites/{site}/listings/featured`	Current listings marked as featured.
`GET`	`/sites/{site}/listings/{listing}`	Fetch one listing by numeric database ID.
`GET`	`/sites/{site}/listings/{listing}/objects`	Media for one listing.
`GET`	`/sites/{site}/objects`	Search media across the site.
`GET`	`/sites/{site}/objects/{object}`	Fetch one media object by numeric ID.

Only syndicated records are returned. A withheld listing behaves as missing and is not exposed through listing or media endpoints.

Response models and field projection

The list and single-record endpoints return FeedSync's processed REAXML object by default. Its keys vary by property type and feed mapping. A residential sale, rental, business, and commercial listing should not be deserialized into one strict model unless the model permits property-specific fields.

Request an explicit comma-separated projection for a stable, smaller payload:

curl "https://feedsync.com.au/api/v1/sites/SITE_UUID/listings?fields=id,unique_id,feedsync_unique_id,status,price,suburb,processed" \
  --header "Authorization: Bearer fs_your_api_key" \
  --header "Accept: application/json"

Only non-null requested fields are returned. Unsupported fields produce 400. Call /sites/{site}/listings/fields during development to inspect supported listing, detail, and computed fields; do not call it before every sync.

Different endpoint shapes

List and single-record operations return processed or projected data. Search returns a fixed summary schema. Featured listings return the normalized listing schema. Model these separately in a typed client.

List and filter

curl --get "https://feedsync.com.au/api/v1/sites/SITE_UUID/listings" \
  --header "Authorization: Bearer fs_your_api_key" \
  --header "Accept: application/json" \
  --data-urlencode "status=current,sold" \
  --data-urlencode "type=residential" \
  --data-urlencode "state=NSW" \
  --data-urlencode "min_price=500000" \
  --data-urlencode "sort=mod_time" \
  --data-urlencode "order=desc" \
  --data-urlencode "per_page=50"

The Listings OpenAPI reference lists every parameter. Important details are:

Area	Current behavior
Pagination	`page` starts at 1. `per_page` normally defaults to 20 and is capped at 100.
Status	One value or a comma-separated set of `current`, `sold`, `leased`, `withdrawn`, `offmarket`, `deleted`.
Type	`residential`, `rental`, `holiday_rental`, `rural`, `commercial`, `land`, `commercial_land`, or `business`.
Bedrooms/bathrooms	Exact counts. Older documentation incorrectly described them as minimum counts.
Office	`agent_id` is the REAXML office `agentID`, not an individual agent. It accepts comma-separated values.
Individual agent	Use `agent_username` or `agent_email`.
Features	Repeat the array parameter, for example `features[]=pool&features[]=air_conditioning`; every requested value must exist.
Dates	`created_from/to`, `updated_from/to`, and `mod_from/to`; to-date filters include the supplied calendar day.
Sorting	Defaults to `mod_time desc`; allowed columns are defined in OpenAPI.

Price and area filters compare stored numeric values. Confirm units in the feed contract before displaying area or money.

Pagination

{
  "data": [
    {
      "id": 1234,
      "unique_id": "CRM-10001",
      "status": "current",
      "price": 850000,
      "suburb": "Fremantle"
    }
  ],
  "meta": {
    "feed_id": 17,
    "feed_name": "Example CRM",
    "total": 142,
    "per_page": 50,
    "current_page": 1,
    "last_page": 3,
    "from": 1,
    "to": 50
  },
  "links": {
    "first": "https://feedsync.com.au/api/v1/sites/SITE_UUID/listings?page=1",
    "last": "https://feedsync.com.au/api/v1/sites/SITE_UUID/listings?page=3",
    "prev": null,
    "next": "https://feedsync.com.au/api/v1/sites/SITE_UUID/listings?page=2"
  }
}

Follow links.next until it is null. Generated links preserve the current query.

Search

curl --get "https://feedsync.com.au/api/v1/sites/SITE_UUID/listings/search" \
  --header "Authorization: Bearer fs_your_api_key" \
  --header "Accept: application/json" \
  --data-urlencode "q=Brisbane Street" \
  --data-urlencode "status=current"

q performs a case-insensitive substring match on the full address.
location matches suburb or full address and exactly matches postcode.
lat and lng must appear together. radius is kilometres, defaults to 10, and accepts 1–100.
date_from and date_to filter mod_time.
Search accepts one status, unlike the list endpoint's comma-separated set.

Search returns a stable summary of identifiers, address, pricing, features, coordinates, category, and modification times. It does not apply list field projection.

Get one listing

curl "https://feedsync.com.au/api/v1/sites/SITE_UUID/listings/1234?fields=id,unique_id,status,processed" \
  --header "Authorization: Bearer fs_your_api_key" \
  --header "Accept: application/json"

{listing} currently accepts the numeric id from a list or search response. It does not resolve ref, unique_id, or feedsync_unique_id. The listing-media operation below supports broader identifiers.

Featured listings

GET /sites/{site}/listings/featured returns syndicated records that are current and marked featured: yes in processed details. Results use mod_time desc; per_page is capped at 50.

Use comma-separated include=details,agents,objects,metadata when those relationships are needed. Included relationships increase response size.

Listing media

/listings/{listing}/objects accepts a numeric listing ID, feedsync_unique_id, or unique_id:

curl --get "https://feedsync.com.au/api/v1/sites/SITE_UUID/listings/CRM-10001/objects" \
  --header "Authorization: Bearer fs_your_api_key" \
  --header "Accept: application/json" \
  --data-urlencode "file_type=image" \
  --data-urlencode "per_page=100"

Objects expose their type, URL, title, timestamps, and whether an image is hosted on FeedSync's CDN. /sites/{site}/objects also supports listing ID, source listing ID, object type, URL/title/description search, creation dates, sorting, and pagination.

Errors and limits

Status	Meaning	Client action
`400`	Unsupported projection field or another malformed request.	Correct the request.
`401`	API key absent, invalid, or not associated with an agency.	Replace or configure the key.
`402`	No active subscription.	Renew; repeated retries will not help.
`403`	Missing `listings:read`, inactive site, or site access denied.	Correct key scope or site configuration.
`404`	Site, feed, listing, or object is unavailable to this key.	Verify identifiers and availability.
`422`	Query validation failed.	Correct fields listed in the `errors` object.
`429`	Per-minute or plan-period allowance exceeded.	Respect `Retry-After` and back off.

Responses normally include X-RateLimit-Limit and X-RateLimit-Remaining; unlimited plans bypass those counters. The minute limit is shared by keys attached to the same site.

Recommended synchronization

Request listings ordered by mod_time desc with an explicit projection.
Follow links.next until it is null.
Upsert by id or feedsync_unique_id; never use an address as identity.
Preserve terminal statuses such as sold, leased, and withdrawn.
Refresh media when its listing changes.
Run periodic full reconciliation so client downtime or mapping corrections cannot leave records stale indefinitely.

Use connection and response timeouts. Retry transient 429 and 5xx responses with capped exponential backoff and jitter, and never log the API key.

Requirements​

Endpoints​

Response models and field projection​

List and filter​

Pagination​

Search​

Get one listing​

Featured listings​

Listing media​

Errors and limits​

Recommended synchronization​