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.