Welcome to the Kato Listing API. This guide walks you through how to build your own property search using our API — from getting connected to going live.
For full technical details, refer to our Kato API Documentation.
👉 See also: Anatomy of a good property search (link to UX best practice page)
1. The basics
1.1 Authentication
All API requests require token-based authentication. Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
1.2 Pagination
When querying a 'List' endpoint, the response will be paginated for performance.
If for example there are 100,000 results, pagination allows the results to be returned a page at a time.
You can use the limit parameter to change how many results are returned per page.
The default page size is specified varies depending on the end point requested.
You can use the page parameter to select which page you want to see.
For example, if the limit is 50, page 1 would return results 1 to 50, page 2 would return results 51 to 52 etc.
At the bottom of each response you will see a pagination block providing a summary of the data you have requested. This appears as follows:
from: First result this pageto: Last result this pagetotal: Count of results in totalcount: Count of results this pageper_page: Number of results per page (see limit param)current_page: Current page number (see page param)total_pages: Total number of pageslinks:first: Navigate to the first pageprevious: Navigate to the previous pagefastback: Navigate 10 pages backnext: Navigate to the next pagefastforward: Navigate 10 pages forwardlast: Navigate to the last page
Take careful note of the total_pages count. If there are more than one, simply update the request to fetch page 2 of the results.
When using the links provided, don't forget to append any additional search params.
1.3 Rate limiting
Requests are limited to 60 per minute.
If you have exceeded your quota, a "429: Too Many Requests" response will be received.
2. Fetching Listings: List Availability
Use the List Availability endpoint to retrieve a list of available properties.
Endpoint
GET /v2/availability
Purpose
Returns a paginated list of current property listings based on specified search criteria.
Key Query Parameters
Parameter | Description |
| Filter listings updated after this date. |
| Pagination control — specify page number. |
| Results per page. |
Example request
https://client-api.agents-society-sandbox.com/v2/availability?updated_from=2023-07-07
Response Structure
Each listing in the response includes the below information, use this data to populate your search results or listings page. The full response can be found on the API docs, but below highlights the key attributes you'll want to use to build your results pages.
Attribute | Explainer |
Meta data | Use to extract and order listings |
| Unique identifier for the listing. |
| Object defining whether the listing is published, featured, and display settings. |
| Timestamp of when the availability was first created in the system. |
| Timestamp of the most recent update to this availability record. |
| Current availability status of the property (e.g., available, under offer). |
Location data | Use to plot on a map and search |
| Object containing full address details including building name, line1, town, country. |
| Geolocation data with lat and lng values for map placement. |
Availability data | Use to build your result cards and also to filter by |
| Array of property types (key & label) such as “office”, “retail”, etc.
💡 Properties can have multiple types |
| Object showing size range (from, to) in square feet/metres.
💡 Ensure you use the normalised |
| Boolean indicating if the property is available to let. |
| Boolean indicating if the property is for sale. |
| Object with rental details: currency, price range, metric (e.g., per sqft). |
| Object with sale price details if for sale. |
| Array of image objects with id, name, and url for each property image.
💡 Use the first image as your index thumbnail. |
3. Fetching Property Details: Show Availability
Use the Show Availability endpoint to get full details for a specific listing.
Example request
GET /v2/availability/217027
Purpose
Returns full details for a single listing, used to build your property detail pages.
Response Structure
Each listing in the response includes the below information, this data is ideal for constructing a detailed property page. The full response can be found on the API docs, but below highlights the key attributes you'll want to use to build your property detail pages.
Attribute | Explainer |
Meta data | Use to extract and update listings |
| Unique identifier for the listing. |
| Internal reference number for the availability (e.g., agency or CRM ref). |
| Object defining whether the listing is published, featured, and display settings. |
| Timestamp of when the availability was first created in the system. |
| Timestamp of the most recent update to this availability record. |
| Current availability status of the property (e.g., available, under offer). |
Location data | Use to plot on a map and build your address strings |
| Object containing full address details including building name, line1, town, country. |
| Geolocation data with lat and lng values for map placement. |
Availability data | Use to build your key property details |
| Array of property types (key & label) such as “office”, “retail”, etc. |
| Object showing size range (from, to) in square feet/metres. |
| Boolean indicating if the property is available to let. |
| Boolean indicating if the property is for sale. |
| Object with rental details: currency, price range, metric (e.g., per sqft). |
| Object with sale price details if for sale. |
| Object with service charge information (value, metric, currency, comments). |
| Object with business rates (value, metric, currency, comments). |
| Object for estate-level charges (value, metric, currency, comments). |
| Energy Performance Certificate details including band and score. |
Marketing text & media | Use to enrich the listing with marketing text and rich media |
| Marketing content object: summary, description, location text, specs, key points.
💡 summary - one sentence summarising the opportunity. Useful for lead-in headings. 💡 key_points - typically 4-6 bullet points highlighting standout features 💡 other headings - there are fixed headings and also some additional headings Agents can add themselves. The array spits out these headings and content in the order they want them displayed. |
| Array of image assets for galleries (includes id, name, url).
💡 The order of the images is usually very important for the Agents. 💡 Ensure you localise the images. |
| Array of video links or media assets (if provided).
💡 Array will include a type of either normal video or 360 tour. |
| Array of downloadable documents (e.g., brochures, spec sheets).
💡 Ensure you localise the files. |
| Array of agents or contacts linked to this property, with name, contact info, photo.
💡 Ensure you persist the order of the Agents. 💡 Sometimes you may already have an Agents profile on your website, in that case use the Agents email to marry things up. |
Floor / units | Use to build accommodation tables within a listing. |
| Array of unit-level data (e.g., part floors) with size, rent, availability. |
(Accommodation Table) | Computed view for displaying key marketing data (e.g., unit name, rent, availability).
💡 In Kato the Agents can build an accommodation table, this array helps you extract that and build that within the listing. |
4. Handling Enquiries
Capture user interest with an enquiry form on your property details page.
Endpoint
https://client-api.agents-society-sandbox.com/v2/enquiry
Purpose
Submit applicant enquiries (single property or multi-property shortlist) to Kato in a structured format.
POST format
Every enquiry should include the below data points to ensure the applicant and their enquiry are added correctly to Kato.
Field | Required | Description | Validation / Options |
contact_title | Optional | Title of the contact. | Options: “Mr”, “Mrs”, “Ms”, “Miss”, “Dr”, “Professor”, “Reverend”, “Pastor”, “Rabbi”, “Sister”, “Councillor”, “Sergeant”. |
forename | Optional | Contact’s first name. | Free text. |
surname | Required | Contact’s surname. | Free text. |
Conditionally Required | Contact’s email address. Required if tel is not provided. | Must be a valid email format. | |
tel | Conditionally Required | Contact’s telephone number. Required if email is not provided. | Allowed: digits (0-9), spaces, dashes (-), plus (+), parentheses. |
contact_type | Optional | Defines the relationship type of the contact. | Options: “agent”, “applicant”, “architect”, “asset_manager”, “landlord”, “lessor”, “tenant”, “investor”, “investor_private”, “developer”, “purchaser”, “vendor”, “supplier”, “facilities_manager”, “client”, “property_owner”, “investment_agent”, “solicitor”, “bank”, “contractor”, “planning_consultant”, “other”. |
contact_source | Optional | Numeric code for how the enquiry was received. | Options: 10 (Website), 11 (Telephone), 12 (Email). |
title | Optional | Title of the enquiry requirement. | Auto-generated if lettings is provided. |
comments | Optional | Free text comments or further information. | Free text. |
lettings | Optional | Disposal ID for a specific property. | Must be a valid Disposal ID. Overrides tenures, types, size_from, size_to, title. |
tenures | Optional | Requirement type. | Comma-separated: “tolet”, “forsale”. |
types | Optional | Property type for the enquiry. | Must match valid property types (e.g., “office”, “retail”). |
size_from | Optional | Minimum size requirement. | Must be less than size_to. |
size_to | Optional | Maximum size requirement. | Must be greater than size_from. |
size_unit | Optional | Unit of measurement. | Options: “sqft”, “sqm”, “hectare”, “desks”, “acres”, “beds”. |
Example Request (Single Property Enquiry)
POST /v2/enquiry
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data
contact_title=Mr
forename=Steve
surname=Oven
email=steveoven@example.com
contact_type=applicant
contact_source=10
title=Looking for offices in London
comments=Hi, I am looking for office spaces in central London
lettings=233868
Important Notes
Either email or tel is required (one must be provided).
If lettings is specified, it will override tenures, types, size_from, size_to, and title.
The form-data submission should match the format shown — use key-value pairs.
Enquiry Form UX Recommendations
Use inline validation for email and phone formats.
If you’re supporting shortlists (multi-property enquiries), submit one request per enquiry.
Implement spam protection (e.g., reCAPTCHA or similar).
Ensure clear user confirmation after submission.
5. Keeping data up-to-date
Set up automated jobs to:
Poll for new listings: Regularly check for newly added properties.
Update existing listings: Refresh data to reflect any changes.
Remove inactive listings: Ensure outdated properties are no longer displayed.
Recommended sync frequency: every 2–6 hours, depending on your requirements.
6. Testing and Going Live
Before launching:
Validate your API integration (authentication, search, detail views).
Confirm that data updates flow correctly.
Test edge cases (e.g., empty search results, error handling).
Run through the enquiry submission process.
Monitor performance and response times.
Once testing is complete, proceed to go live 🎉