Skip to content

Listing API

For managers. Your office only sees this when Listing API is turned on. See Office options.

Listing API lets your own system add listings into this office, update them, send photos, and read orders and brochure stats back. A Manager generates a token, authorises it, and can deauthorise it. Users and agents do not see this page.

The Listing API page in the portal has the short steps and the address for the portal you are signed into. This article is the full reference.


Open Listing API

In the top menu, click Listing API.

If you do not see it, the option is off. Ask support.


Token

Button What it does
Generate token Creates a new token and shows it once. If a token already exists, that one stops working immediately. The new token does not work until you authorise it.
Authorise Calls are accepted. If you had deauthorised, the same token works again.
Deauthorise Calls stop immediately. Authorise again to resume the same token.

Copy the token when it is shown. It is not shown again. If you lose it, generate a new one and authorise that one.

The page also shows the start of the token, when it was generated, when it was authorised, and the last call.

The status on the page is No token, Token ready — not authorised, Authorised, or Deauthorised.

Calls work only while the status is Authorised, and only while Listing API stays on for this office. Turning the option off stops calls. Turning it back on resumes an authorised token.

One office has one token. Use that token. A Grok Bot token is refused.


Calls

Every call sends:

Authorization: Bearer mhe_…
Portal Address
Australia https://myhubexpress.app/api/listings.php
United States https://us.myhubexpress.app/api/listings.php

The Listing API page shows the address for the portal you are signed into.

action may be in the query string or in the JSON body. These actions may be GET. The others are POST.

Action Method What it does
whoami GET Confirms the token and returns this group
lookups GET Ids and field names for this office
get GET Reads one listing
order_status GET Every order on that listing, with status times
brochure_stats GET QR scans and brochure opens
create POST Adds a listing
update POST Changes a listing this API created
image POST Stores photos
complete POST Sets Add to completed
reopen POST Sets Add back to in progress
send_approval POST Texts Agent 1 a link to one pending brochure or board

JSON calls use a JSON body. Photo files use a form upload (multipart), with action and external_id as form fields. Form fields are used when the same name is not already in the JSON body.

external_id is your id for the listing. It may contain letters, numbers, and . _ : @ / | -, up to 191 characters. The same external_id always means the same listing for this office.

update, image, complete, reopen, get, order_status, brochure_stats, and send_approval also accept property_id, the id this portal assigned. If you send both, external_id is the one that is used. property_id works for a listing this API created. A listing that arrived from a CRM file, and a listing someone added by hand in the portal, cannot be changed here.

An update changes only the keys you send. Keys you leave out stay as they are. Send an empty string to clear a field you are allowed to clear.

HTTP When
401 The token is missing, wrong, or not authorised, or Listing API is off
405 A write was sent as GET
400 The action, a field, the type, or orders is not valid. If Product orders is off, sending orders refuses the whole call and does not write the listing
404 No listing for that external_id, the property_id was not created by this API, or the order is not on this listing
409 Send for Approval, when the order is not pending or Agent 1 has no active MRE Agent App
422 complete, before long copy and a stored photo exist. missing lists description, image, or both
502 The approval text could not be sent

MCP

An MCP client uses this same token and these same rules. Each tool is passed through to the Listing API. There is no second token.

Portal Address
Australia https://myhubexpress.app/mcp/listings
United States https://us.myhubexpress.app/mcp/listings

The Listing API page shows the address for the portal you are signed into.

Send the token on every call:

Authorization: Bearer mhe_…
Tool Action
listings_whoami whoami
listings_lookups lookups
listings_get get
listings_order_status order_status
listings_brochure_stats brochure_stats
listings_create create
listings_update update
listings_image image
listings_send_approval send_approval
listings_complete complete
listings_reopen reopen

listings_image sends public https links. Photo files stay on POST /api/listings.php with action image.

A missing, wrong, or unauthorised token is refused before any tool runs. A Grok Bot token is refused.


Check the token

GET ?action=whoami

A live token returns success, "authorised": true, customer_id, customer_name, and "api": "listings". customer_name is the group on the account. The branch offices are not in this reply. They are offices on lookups.


Read the ids

GET ?action=lookups

Use the ids from this reply. Send the id, not the display name.

Key What it contains
offices id and name
agents Active agents, id and name. This is Agent 1 and Agent 2
banners id and name. 0 is None
property_types value and label for type
sell_methods 0 to 6
lease_periods week, month, year
categories Values for category
commercial_categories Values for commercialcategory
size_units Unit names the portal uses. See Rooms and size
yes_no yes and no
fields Every field name this API accepts, with its label
add inprogress and completed
orders Products you may order. Present only when Product orders is on for this office

fields on this reply is the list to trust. A name that is not in that list is refused. The tables below are that same list.


Add a listing

POST JSON with action create.

external_id, suburb, and type are required. The new listing has Add = inprogress. On the listing, under the address, you see Add: In progress. Office automation does not run yet.

If you leave listing date out, it is set to the time of the call. active defaults to yes. locked defaults to no.

Sending the same external_id again returns that listing and does not create a second one. The reply has "created": false. If that second call includes orders, those requests are still stored.

{
  "action": "create",
  "external_id": "your-listing-1",
  "number": "12",
  "specific": "Smith",
  "generic": "Street",
  "suburb": "Bendigo",
  "postcode": "3550",
  "type": "residential",
  "active": "yes",
  "locked": "no",
  "fields": {
    "office": "3",
    "agent": "99",
    "agentalt": "100",
    "banner": "0",
    "sellmethod": "0",
    "heading": "Family home close to town",
    "description": "Long copy goes here.",
    "price": "750000",
    "bedrooms": "4",
    "bathrooms": "2",
    "carspace": "2"
  }
}

The reply is the listing, as in Read a listing, plus created. When this call included orders, orders is the result of those items. See Product orders.


Address, type, and status

These sit on the listing itself. Send them beside external_id, not inside fields.

Name Required on create What to send
suburb Yes Suburb. An update cannot leave it empty
type Yes A value from property_types
number No Street number
specific No Street name
generic No Street type, such as Street or Road
postcode No The postcode on the address. This is the postcode on the listing screen
active No yes or no. Default yes
locked No yes or no. Default no. Locked listings stay locked for editing in the portal
type Label
residential Residential
rural Rural
commercial Commercial
business Business
land Land
rental Rental

There is also a field named postcode inside fields. That one does not change the address postcode. Send the address postcode as its own key, as in the example above.


Fields

Everything else goes in fields, using the names from lookups. The name in the first column is what you send. The label is the usual name on the listing. Field Manager can rename the label. The API name stays the same.

A field that has a Max for this office is refused when the text is longer. A single field longer than 100,000 characters is refused. add is not set inside fields. Use complete and reopen.

Calendar dates such as listing date, sold date, and auction date are YYYY-MM-DD HH:MM:SS.

yes / no fields are live, magazine, sold, and withdrawn. Any other word is refused. An empty string clears the value.

Place and price

Name Usual label What to send
state State Text
city City Text
country Country Text
address_online Full address (online) Text
category Category One value from the category list below, copied exactly
commercialcategory Commercial category One value from the commercial list below, copied exactly
webid Web ID The listing web address. When this value changes, the QR short link is written into url
mls_id MLS ID Text
school_district School district Text. Accepted on both portals. The box shows when US listing fields are on
subdivision Subdivision Text. Same as school district
unit_number Unit number Text. Same as school district
url Property URL Text. A changed webid also writes the short link here
price Price Text
priceprepared Display price Text
sellmethod Sell method 0 to 6. See below
period Lease period week, month, or year
landrates Land rates Text
waterrates Water rates Text

Sell method: 0 For sale, 1 Auction, 2 EOI, 3 POA, 4 Tender, 5 Contact agent, 6 Lease.

Lease period: week weekly, month monthly, year yearly.

Category, copied exactly:

House, Unit, Townhouse, Villa, Apartment, Flat, Studio, Warehouse, DuplexSemi-detached, Alpine, AcreageSemi-rural, BlockOfUnits, Terrace, Retirement, ServicedApartment, Other.

Commercial category, copied exactly:

Commercial Farming, Land/Development, Hotel/Leisure, Industrial/Warehouse, Medical/Consulting, Offices, Retail, Showrooms/Bulky Goods, Other.

Rooms and size

Name Usual label What to send
bedrooms Bedrooms Text
bathrooms Bathrooms Text
carspace Car space Text
garagespace Garage space Text
carportspace Carport space Text
livingrooms Living rooms Text
study Study Text
year_built Year built Text
virtual_tour_url Video A link
landsize Land size The number
buildingsize Building size The number
land_size_acres Land size (acres) Text. Shows when US listing fields are on

lookups includes size_units: squareMeter (m²), hectare, acre, square, and sqft. Land size and building size are the numbers in landsize and buildingsize. The unit stays the one already on the listing. landunit and buildingunit are refused.

Listing status

Name Usual label What to send
listdate Listing date YYYY-MM-DD HH:MM:SS. On create, omitted means now
live Live yes or no. yes creates the webbook when this office has one and the listing does not yet
magazine Show in magazine yes or no
banner Banner A banner id from lookups, or 0 for none
auctiondate Auction / EOI date One date and time. See Auction and inspection times
exclusivity Exclusivity open or exclusive
date_modified Last updated YYYY-MM-DD HH:MM:SS
inspection Inspection One text value. See below
sold Sold yes or no
solddate Sold date YYYY-MM-DD HH:MM:SS
soldprice Sold price Text
withdrawn Withdrawn yes or no
agent Agent An active agent id from lookups
agentalt Agent 2 An active agent id from lookups
office Office An office id from lookups

Copy

Name Usual label What to send
heading Heading Text
headline Headline Text
description Long copy Text. Required before complete
headingalt Magazine heading Text
descriptionalt Magazine copy Text
headingextra Short heading Text
descriptionextra Short copy Text
headingextra2 Copy 4 heading Text. Hidden on the Copy tab until this office turns that field on. An office may rename it, for example Web Heading
descriptionextra2 Copy 4 Text. Same as Copy 4 heading
headingextra3 Copy 5 heading Text
descriptionextra3 Copy 5 Text
headingextra4 Copy 6 heading Text. Some offices use this as the signboard heading. It can still be sent after Add is completed
descriptionextra4 Copy 6 Text
videolink Video link A link
point1 … point6 Feature 1 … Feature 6 Text. One field per point

Heading, long copy, price, rooms, and the other fields in these tables can still be changed after Add is completed.

Magazine heading, magazine copy, short heading, short copy, and Copy 4–6 stay as they are once this office has locked that field. The call still succeeds. headingextra4 can still be sent after Add is completed. Sending text in headingextra4 locks that field.

Reviews and sold statistics

Name Usual label
vendorrating Vendor rating
vendordate Vendor date
vendortitle Vendor title
vendorreview Vendor review
purchaserrating Purchaser rating
purchaserdate Purchaser date
purchasertitle Purchaser title
purchaserreview Purchaser review
statementinfo Statement info
statementvendor Statement vendor
sipages SI pages
vspages VS pages
solddays Days on market
soldinspections Inspections
soldoffers Offers received
soldviews Views

Names that are refused

These names are kept by the portal. A call that sends one is refused:

latitude, longitude, status, landunit, buildingunit, agent_name, office_name, feed_listing_id, feed_provider_id, feed_checksum, feed_synced_at.

Open-for-inspection start and end are not fields on this API. Use inspection.


Auction and inspection times

Auction. In fields, set sellmethod to 1 and auctiondate to one date and time, YYYY-MM-DD HH:MM:SS. There is no separate time field.

Inspection times. inspection is one text value, the same box as on the listing. Each open home is four words: date, start, to, end. Several upcoming times go in that same string, separated by spaces:

2026-10-18 11:00 to 11:30 2026-10-25 14:00 to 14:30

An update replaces the whole value. Send every time you want kept. Times you leave out are removed, including past times. An empty value clears it. By Appointment is the other accepted value. The Inspection option must be on for this office for the box to show on the listing. The API stores the text either way.


Change a listing

POST action=update with external_id (or property_id) and the address keys or fields to change.

A listing that arrived from a CRM file cannot be changed here. A listing added by hand in the portal cannot be changed here.

Heading, long copy, and the other unlocked fields can be changed after Add is completed. Locked extra copy fields stay as they are, except headingextra4. See Copy.


Photos

POST action=image.

Send JPEG, PNG, GIF, or WebP. Each file is up to 15 MB. One call takes up to 20 photos.

Positions run from 1 to 40. Position 1 is the main photo. Position 5 is the floor plan. A number outside 1–40 is stored with no position.

Files use the form field image or image[]. position[] (or positions) is in the same order as the files. The form field may also be named images.

Public https links use image_url for one photo, or images as a list. Each item is url and position, or a URL string with no position. The link must be the image file itself. A link that redirects is refused. A private or local address is refused. This host downloads the file and stores it on the listing. A link left as a web address does not count as an uploaded photo, so it does not satisfy complete.

A list of links with no position on each one is stored and does not change a brochure. A photo sent with no position is added and does not change an existing order.

A link of a photo already on the listing is saved again into the position you name. The file that was in that position stays on the listing with no number. The file you copied from keeps its old position. Sending a position that already has a photo puts the new file in that position. Each still-pending brochure or board that was using that photo is updated, and its proof is refreshed once for that call. The reply lists those orders in orders_updated, each with id and kind. Agent 1 is not texted for that change. An approved, printed, or dispatched order is left as it is.

If every photo in the call fails, the reply is unsuccessful and includes errors. If some are stored, success is true, images lists the stored ones, and errors lists the rest. Each stored photo has id, filename, and position. A replaced position has "replaced": true.

There is no call to delete a photo.

Several photos in one call:

{
  "action": "image",
  "external_id": "your-listing-1",
  "images": [
    {"url": "https://photos.example/front.jpg", "position": 1},
    {"url": "https://photos.example/kitchen.jpg", "position": 2}
  ]
}

Finish

POST action=complete with external_id.

This sets Add = completed. It is refused until long copy (description) and at least one stored photo exist. A photo that is still only a web address does not count. The reply then includes missing.

The listing shows Add: Completed. This office's automation runs on the next pass, within about five minutes, for the options that are turned on (Web ID, photo tools, copy tools, brochures, and the rest).

orders may be included on this call. See Product orders.


Pause

POST action=reopen sets Add back to in progress. Work already finished stays. Further automation waits until you complete again. An order already created is left as it is. This call does not store orders.


Product orders

Only when this office has asked for Product orders. On create, update, or complete, send orders as a list of ids from lookups. lookups includes orders only when this is on.

Sending orders while the option is off returns 400 and does not write the listing. Leave orders out and the listing changes only. An update that leaves orders out does not remove an earlier request. An empty list adds nothing and does not cancel an earlier request.

Each product in lookups → orders has:

Key Meaning
id The id you send. A number, or signboard_qr
type template, document, or signboard
name The product name
quantity The default quantity
quantities Every extra QTY option on that template. An empty list means there are none

Leave quantity out and the order uses quantity, the default. An empty quantities list means that default is the only one, often 1. An A3 brochure whose QTY option is 25 is ordered as 25, and 25 is in quantities. Send {"id":123,"quantity":50} only when 50 is in that list. A number that is not an option is refused for that item. The other items in the same call are still stored, and the listing is still saved.

Use those ids. A name is refused. A magazine is left out of lookups and is refused if you send its id. The same id twice in one call counts once.

signboard_qr is the Signboard QR Label when Signboard QR is on for the office. A brochure must already be marked Include in Auto Brochure Creation. Signboard QR uses its own option, not that tick. The Signboard QR Label is ordered at its default quantity. A quantity you send for it is still checked against that product's options, and the order that is built uses the default.

The call stores the request. It does not build the PDF. The pending order is created on a later pass, after Add is completed, after image position, copy, and watermark work have finished when those are on, and when Agent 1 has an active MRE Agent App. The same product is not ordered twice on the same calendar day. A different product the same day is allowed. The next day can order that product again. Approving one of these orders does not cancel the others.

Each item in the reply has id, type, name, status, reason, and order_id.

status Meaning
queued Stored. The order is built after Add is completed, or on the next pass if the listing is already ready
waiting_ready Waiting until image position, copy, and watermark work have finished, or until the Signboard QR check passes
waiting_agent Agent 1 does not have an active MRE Agent App
exists This product was already requested or ordered for this listing today
refused The id, the quantity, or the option is not valid for this office
done On a later get, the pending order has been created
{
  "action": "complete",
  "external_id": "your-listing-1",
  "orders": [123, {"id": 456, "quantity": 50}, "signboard_qr"]
}

On create, update, and complete, orders in the reply is the result of the list in that call. The history of requests is on get.


Read a listing

GET ?action=get&external_id=your-id

property_id may be used instead, for a listing this API created.

Key What it is
property_id This portal's id
external_id Your id
number, specific, generic, suburb, postcode Address
type Property type
active, locked yes or no
add inprogress or completed
fields Each stored field value. Names match Fields
images Active photos. Each has id, filename, position (null when it has no number), and url
orders Up to 50 recent product-order requests, newest first. Included only when Product orders is on. Each has request_date, status, reason, and order_id

This call does not change the listing.


Order status

GET ?action=order_status&external_id=your-id

Returns every order on that listing, including orders made in the portal. It does not change the listing or the order. Poll this after you trigger an order.

The reply has property_id, external_id, timezone, and orders. Each order has:

Key What it is
id The order id. Send this as order_id on Send for Approval
kind template or document
product_id The product
name The product name
quantity The quantity on the order
status The current status, including cancelled
status_at The first time it was marked pending, approved, printed, or dispatched

A status that has not happened yet is null. Times are this office’s local time, ISO 8601, with the timezone offset. timezone is the name of that zone.

Product orders do not have to be on for this call. It reads orders that already exist.


Brochure stats

GET ?action=brochure_stats&external_id=your-id

Returns QR scans for that listing. It does not change the listing. Product orders do not have to be on.

Key What it is
total All time
week The past 7 days
month The past 30 days

Each of those has scans, brochure_opens, and clicks. scans are QR scans. brochure_opens are opens of the brochure. clicks is the two added together. week and month also include daily, one row per day, with date, scans, brochure_opens, and clicks. total has no daily list.


Send for Approval

POST action=send_approval with external_id and order_id from order status.

kind is template or document, the same kind on that order. order is accepted for a template order. order_type may be sent in place of kind. If you leave kind out and the id matches one order on this listing, that order is used. If the same id exists as both a template order and a document, send kind.

This texts Agent 1 one link to that pending brochure or board. The text names the product. The reply includes sent_to, Agent 1’s name, plus order_id and kind.

The first text is sent when the pending order is first ready. Call this after later changes, once they are ready for the agent. It can be sent again later. An order that is not pending is refused. A magazine is refused. Agent 1 must have an active MRE Agent App. Product orders do not have to be on. The order must already exist and be pending.

{
  "action": "send_approval",
  "external_id": "your-listing-1",
  "order_id": 12345,
  "kind": "template"
}

Approving, printing, and dispatch stay in the portal and the MRE Agent App. This call only sends the text.


One listing at a time

Each call names one listing by external_id or property_id. This API adds photos and replaces a position. Deleting a listing or a photo, and approving, printing, or dispatching an order, stay in the portal and the MRE Agent App.