The Homebinding API
Every listing, place, price, sale record, auction, stay and review on Homebinding is reachable by a documented interface, so that agents, solicitors, lenders, channel managers and developers can build on the platform rather than around it. The specification is published as OpenAPI 3.1.
The Homebinding API
Homebinding runs one platform across work usually split between half a dozen systems: sales and lettings of every kind, timed online auctions, deposit backed sales on a single transaction record, holiday lets, sold prices, official copies from HM Land Registry, brochures and printing, Bind It cleaners, work exchange, video, directories, place pages, reviews, agents and jobs. The API exposes it to software: plain REST over HTTPS from https://api.homebinding.co.uk/v1.
That specification describes what the platform is designed to expose. What is actually running today, with what it is holding and when each part last ran, is on the back end page.
It serves three sorts of work: reading published data such as listings and sold prices; writing for a client, so an agent can list and take offers from their own software; and following a sale through its eleven stages. The file is version 1.1.0, an OpenAPI 3.1 document, and a design specification rather than a record of something running, so read every field name and limit as provisional.
Who gets keys
There are two kinds of credential. A public key is read only, for data already published: listings, places, prices, sold prices, the HM Land Registry fee table and forms catalogue, directories, cleaners, work exchange hosts, video, auction catalogues, reviews, profiles and vacancies. It goes in the X-Homebinding-Key header, is tied to a named application, and never writes or reads personal data.
Everything else uses OAuth 2.0 client credentials, issued to an organisation after onboarding: agents and auctioneers, conveyancers, lenders, channel partners and Homebinding Approved firms. Tokens are short lived and carry only the scopes asked for, such as listings:write. Every partner call is attributed to that organisation in the audit trail: on a deposit backed sale it should be clear who did what and when. Joining as an agent is free, but an account is not a credential.
People who use the site sign in as members and stay signed in. A member session is what saves a listing with the heart, orders official copies, adds a picture against a sale or applies to a work exchange host; it belongs to a person, where a partner credential belongs to an organisation.
The resource map
| Resource | What it does | Who may call it |
|---|---|---|
| Listings | Search, read, create, update, publish; photographs and the four films; room sizes in metres and in feet; the public documents folder; nearby sales and similar homes. Every type, from flats to farms, boats, modular homes and castles. | Public key to read, owner or agent token to write. |
| Sold prices | HM Land Registry sales as their own section: search by postcode, place or radius; one sale with its EPC match and price per square metre; valuer's notes with three to six pictures; pictures against a sale; the discussion thread. | Public key to read; member session or surveyor's token to contribute. |
| Places and prices | Place search, neighbourhood data, worship nearby, sold prices per square metre, House Price Index. | Public key. |
| Land Registry | Title numbers for an address, the fee table in force, official copies at HM Land Registry's own fee paid through Stripe, and the catalogue of every HM Land Registry form. | Fees and forms public; titles and orders by member session or partner token. |
| Members and referrals | The signed in person, saved listings with the heart, the referral code and link, invitations by email. | Member session. |
| Offers | Make an offer, record the vendor's decision. Acceptance opens the transaction record. | Partner token. |
| Reservations | Create and sign the mutual reservation agreement, extend the long stop date, read deposit status. | Partner token. |
| Transactions | Read the record, move it between the eleven stages, add documents. | Parties to that transaction. |
| Conveyancing | Order and track searches, assemble the legal pack. | Solicitors and conveyancers on the sale. |
| Auctions | Auctions and lots, bidder registration, bidding, current price. | Catalogue public, bidding by token. |
| Stays | Availability, quotes, bookings, cancellations. | Quotes open, bookings by token. |
| Channel manager | Homebinding Host: connect Airbnb and Booking.com, sync, export and import iCal. | The stay's owner or manager. |
| Bind It cleaners | Certified cleaners by place, cleaning jobs on a stay tied to a booking, linen providers. | Directory public; jobs by token. |
| Directories | Stays, care homes and places of worship. | Public key. |
| Work exchange | Hosts offering board and lodging for help, and applications to them. | Public to read, member session to apply. |
| Reviews | Leave a review tied to a recorded viewing, read moderation status. | Public to read, verified viewing to write. |
| Agents and jobs | Join, maintain a profile, list vacancies. | Public to read, own token to edit. |
| Videos | The video layer, pulled through from YouTube by topic and place. | Public key. |
| Brochures | Build the sixteen page brochure on the Homebinding template and order printed copies through Gelato. | Owner or agent token. |
| EPC | Certificates by postcode or number, with the floor area behind price per square metre. | Partner token, personal data. |
| Webhooks and health | Subscribe to events, list event types, check the service. | Token to subscribe, health open. |
Money is whole pence in a field ending in Pence, currency GBP. Dates are ISO 8601. Collections are cursor paginated, and every error uses one object with a stable code and a request identifier.
Webhooks and rate limits
Webhooks
Rather than polling, register an HTTPS endpoint and the events it should receive: a listing published or its price changed, an offer accepted, a transaction changing stage, a deposit cleared, a bidder approved or a lot closed, a booking made, a calendar synced, a cleaning job moving, a brochure ready or a print order moving, an official copy ready, a payment succeeded, a valuer's note added, a referral qualified, a review published. Deliveries are signed with a secret shown once at creation, so check the signature before trusting the body. Delivery is at least once, so key your handler on the event identifier. A failing endpoint is retried for about a day, then marked as failing.
Rate limits
Limits are given in words, not one number, because they differ by credential. A public key is metered generously for browsing and search, and throttled if used to walk the whole index. Partner tokens get more, with a tighter allowance for calls that cost money or reach a third party. Bidding is limited per bidder, not per application, so no client can crowd an auction. Going over returns a refusal and a header saying how long to wait.
The OpenAPI 3.1 source in YAML, for any OpenAPI tool. This is not advice, and the specification is a design document, not a contract.
How this fits the site
Everything the API returns is something the site itself uses. A listing created through the API is the record a seller creates through the listing form, and passes the same publication checks: address, photograph, price, tenure and an EPC certificate number or exemption. An offer made through it opens the same transaction record, with the same stages, documents and stakeholder held deposit.
Sources: HM Land Registry for Price Paid Data and the UK House Price Index, the Ministry of Housing, Communities and Local Government for the Energy Performance of Buildings register, and the Office for National Statistics for local authority codes. Open data is published under the Open Government Licence and attributed in the responses carrying it.
