Partner API

The Bali Homes issues each partner agency an API key. Send it in the Authorization header of every request.

Authorization: Bearer tbh_pk_xxxxxxxxxxxxxxxxxxxxxxxx

• You see the key once, when it is issued. Store it in a secret manager or environment variable.
• Call the API from your server only. Keys placed in browser or mobile app code can be copied.
• Every request is logged against your key. If a key leaks, ask us to revoke it and we will issue a new one.
• Requests without a valid key get 401. Revoked keys get 403.

GET/listings

Returns available listings, newest first, one page at a time. Each item is a full listing object, including the description and the complete gallery.

curl "https://www.thebalihomes.com/api/partner/v1/listings?location=canggu&limit=50" \
  -H "Authorization: Bearer $TBH_API_KEY"

{
  "listings": [ /* listing objects */ ],
  "page": { "limit": 50, "offset": 0, "total": 155 }
}

To download the whole catalogue, increase offset by limit until you have total listings.

GET/listings/{code}

Returns one listing by its KES code, for example KES539. Codes are case-insensitive and stay the same when a listing's title or URL changes. Units inside a development can carry a suffix, such as KES601-2.

curl "https://www.thebalihomes.com/api/partner/v1/listings/KES539" \
  -H "Authorization: Bearer $TBH_API_KEY"

The response is { "listing": { … } }. If the listing is no longer available you get 404. Treat that as removed and take it off your site.

GET/listings/changes?since={timestamp}

Returns everything that changed after since, an ISO 8601 timestamp such as 2026-10-23T08:00:00Z. Use it to keep your copy up to date without downloading the full catalogue again.

curl "https://www.thebalihomes.com/api/partner/v1/listings/changes?since=2026-10-23T08:00:00Z" \
  -H "Authorization: Bearer $TBH_API_KEY"

{
  "updated": [ /* listing objects */ ],
  "removed": ["KES487", "KES513"],
  "nextSince": "2026-10-23T08:15:02.311Z"
}

GET/meta

Returns the values used in listing fields and filters: location slugs with display names and the number of available listings, property types and contract types.

{
  "locations": [
    { "slug": "uluwatu", "name": "Uluwatu", "listings": 61 },
    { "slug": "canggu", "name": "Canggu", "listings": 50 }
  ],
  "propertyTypes": ["off-plan", "ready", "renovation-project"],
  "contractTypes": ["leasehold", "freehold"]
}

Fields are null when we don't have the value. Media URLs are absolute and served from media.thebalihomes.com.

{
  "code": "KES539",
  "title": "Three-bedroom villa with rice field views",
  "propertyType": "ready",
  "contractType": "leasehold",
  "leaseholdYears": "27",
  "location": "canggu",
  "locationDetail": "Pererenan",
  "latitude": -8.6412,
  "longitude": 115.1268,
  "priceUsd": 385000,
  "priceIdr": 6300000000,
  "bedrooms": 3,
  "bathrooms": 3,
  "landSizeM2": 300,
  "buildSizeM2": 210,
  "pool": "Private",
  "parkingLots": 1,
  "furniture": "Fully furnished",
  "deliveryDate": null,
  "shortDescription": "Modern tropical villa a short drive from Pererenan beach.",
  "body": "<p>…</p>",
  "featuredImage": "https://media.thebalihomes.com/…/cover.jpg",
  "thumbnail": "https://media.thebalihomes.com/…/thumb.jpg",
  "gallery": ["https://media.thebalihomes.com/…/01.jpg"],
  "url": "https://www.thebalihomes.com/listing/three-bedroom-villa-pererenan",
  "publishedAt": "2026-09-14T03:20:00.000Z",
  "updatedAt": "2026-10-20T11:02:45.000Z"
}

The example shows the format. The listing and its values are illustrative.

1. Note the current time, then download the full catalogue by paging through /listings.
2. Every 15–60 minutes, call /listings/changes with that time as since. Store nextSince for the next run.
3. Upsert every listing in updated, using code as the key. Remove every code in removed.
4. Sync at least once every 24 hours so sold properties come off your site quickly.

Photo URLs can change when a gallery is edited. That edit shows up in the changes feed, so refresh images when a listing is updated.

Each key may make 120 requests per minute. Every response tells you where you stand:

A full sync of the catalogue takes a handful of requests, so normal use stays well below the limit. Contact us if you need more.

Errors use standard HTTP status codes and return a JSON body with a machine-readable code and a message.

{
  "error": {
    "code": "listing_not_found",
    "message": "No available listing with code KES999."
  }
}