Listings

List your listings, or retrieve a single listing by id.

The listing model

Listings represent properties you publish on Twentybaan. The API returns a stable subset of fields for integrations (spreadsheets, CRMs, automation).

Properties

Name
id
Type
integer
Description
Unique identifier for the listing.
Name
status
Type
string
Description
Publishing status (for example draft, published).
Name
slug
Type
string
Description
URL-friendly identifier for the listing.
Name
title
Type
string
Description
Public title of the listing.
Name
city
Type
string
Description
City of the property.
Name
area
Type
string
Description
Area/neighborhood label.
Name
property_type
Type
string
Description
Property type (for example condo, house).
Name
offer_type
Type
string
Description
Offer type (for example rent, sale).
Name
rent_price_amount
Type
integer
Description
Numeric rent price amount (when applicable).
Name
rent_price_period
Type
string
Description
Rent period (for example month).
Name
sale_price_amount
Type
integer|null
Description
Numeric sale price amount (when applicable).
Name
price_text
Type
string
Description
Human-friendly price text.
Name
beds_text
Type
string
Description
Bedrooms (free-form).
Name
area_sqm
Type
number|null
Description
Floor area in square meters (when available).
Name
image_url
Type
string|null
Description
Primary image URL (when set).
Name
published_at
Type
timestamp|null
Description
Timestamp of when the listing was published.
Name
created_at
Type
timestamp
Description
Timestamp of when the listing was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the listing was last updated.

GET/v1/listings/

List all listings

Retrieve a paginated list of listings owned by the authenticated user. By default, a maximum of 50 listings are returned per request.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of listings returned (default 50, max 200).
Name
before_id
Type
integer
Description
Return listings with id less than this value (cursor pagination).

Required scope

Tokens must include read:listings (OAuth tokens and API keys).

Request

GET

/v1/listings/

curl -G https://api.twentybaan.com/v1/listings/ \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d limit=10

GET

/v1/listings/

const token = process.env.TWENTYBAAN_API_KEY;

const url = new URL("https://api.twentybaan.com/v1/listings/");
url.searchParams.set("limit", "10");

const res = await fetch(url, {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

GET

/v1/listings/

type TwentybaanListingsResponse =
  | { ok: true; items: unknown[]; next_before_id: number | null }
  | { ok: false; error: string };

const token = process.env.TWENTYBAAN_API_KEY!;

const url = new URL("https://api.twentybaan.com/v1/listings/");
url.searchParams.set("limit", "10");

const res = await fetch(url, {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const data = (await res.json()) as TwentybaanListingsResponse;

if (!res.ok || !data.ok) {
  throw new Error("Request failed");
}

console.log(data.items);

GET

/v1/listings/

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

res = requests.get(
  "https://api.twentybaan.com/v1/listings/",
  params={"limit": 10},
  headers={
    "Accept": "application/json",
    "Authorization": f"Bearer {token}",
  },
  timeout=30,
)
res.raise_for_status()
print(res.json())

GET

/v1/listings/

<?php

$token = getenv('TWENTYBAAN_API_KEY') ?: '';

$url = "https://api.twentybaan.com/v1/listings/?" . http_build_query([
  "limit" => 10,
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Authorization: Bearer " . $token,
  ],
]);

$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP {$status}\n";
echo $body;

GET

/v1/listings/

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var token = Environment.GetEnvironmentVariable("TWENTYBAAN_API_KEY") ?? "";
var url = "https://api.twentybaan.com/v1/listings/?limit=10";

using var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var res = await client.GetAsync(url);
var body = await res.Content.ReadAsStringAsync();

Console.WriteLine((int)res.StatusCode);
Console.WriteLine(body);

GET

/v1/listings/

require "net/http"
require "json"

token = ENV.fetch("TWENTYBAAN_API_KEY")
uri = URI("https://api.twentybaan.com/v1/listings/")
uri.query = URI.encode_www_form({ limit: 10 })

req = Net::HTTP::Get.new(uri)
req["Accept"] = "application/json"
req["Authorization"] = "Bearer #{token}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(req)
end

puts res.code
puts res.body

GET

/v1/listings/

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
  "time"
)

func main() {
  token := os.Getenv("TWENTYBAAN_API_KEY")

  u, err := url.Parse("https://api.twentybaan.com/v1/listings/")
  if err != nil {
    panic(err)
  }

  q := u.Query()
  q.Set("limit", "10")
  u.RawQuery = q.Encode()

  req, err := http.NewRequest("GET", u.String(), nil)
  if err != nil {
    panic(err)
  }

  req.Header.Set("Accept", "application/json")
  req.Header.Set("Authorization", "Bearer "+token)

  client := &http.Client{Timeout: 30 * time.Second}
  res, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  body, _ := io.ReadAll(res.Body)
  fmt.Println(res.Status)
  fmt.Println(string(body))
}

Response

{
  "ok": true,
  "items": [
    {
      "id": 123,
      "status": "published",
      "slug": "modern-condo-sukhumvit",
      "title": "Modern condo near BTS",
      "city": "Bangkok",
      "area": "Sukhumvit",
      "property_type": "condo",
      "offer_type": "rent",
      "rent_price_amount": 35000,
      "rent_price_period": "month",
      "sale_price_amount": null,
      "price_text": "฿35,000 / month",
      "beds_text": "2",
      "area_sqm": 62,
      "image_url": "https://...",
      "published_at": "2026-01-01T12:34:56Z",
      "created_at": "2025-12-15T09:12:00Z",
      "updated_at": "2026-01-02T03:45:00Z"
    }
  ],
  "next_before_id": 120
}

GET/v1/listings?id=:id

Retrieve a listing

Fetch a single listing by id. The authenticated user must own the listing.

Required attributes

Name
id
Type
integer
Description
The listing id to retrieve.

Errors

Returns 404 if the listing does not exist or does not belong to the authenticated user.

Request

GET

/v1/listings/

curl -G https://api.twentybaan.com/v1/listings/ \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id=123

GET

/v1/listings/

const token = process.env.TWENTYBAAN_API_KEY;

const url = new URL("https://api.twentybaan.com/v1/listings/");
url.searchParams.set("id", "123");

const res = await fetch(url, {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

GET

/v1/listings/

type TwentybaanListingResponse =
  | { ok: true; listing: Record<string, unknown> }
  | { ok: false; error: string };

const token = process.env.TWENTYBAAN_API_KEY!;

const url = new URL("https://api.twentybaan.com/v1/listings/");
url.searchParams.set("id", "123");

const res = await fetch(url, {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const data = (await res.json()) as TwentybaanListingResponse;

if (!res.ok || !data.ok) {
  throw new Error("Request failed");
}

console.log(data.listing);

GET

/v1/listings/

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

res = requests.get(
  "https://api.twentybaan.com/v1/listings/",
  params={"id": 123},
  headers={
    "Accept": "application/json",
    "Authorization": f"Bearer {token}",
  },
  timeout=30,
)
res.raise_for_status()
print(res.json())

GET

/v1/listings/

<?php

$token = getenv('TWENTYBAAN_API_KEY') ?: '';

$url = "https://api.twentybaan.com/v1/listings/?" . http_build_query([
  "id" => 123,
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Authorization: Bearer " . $token,
  ],
]);

$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP {$status}\n";
echo $body;

GET

/v1/listings/

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var token = Environment.GetEnvironmentVariable("TWENTYBAAN_API_KEY") ?? "";
var url = "https://api.twentybaan.com/v1/listings/?id=123";

using var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var res = await client.GetAsync(url);
var body = await res.Content.ReadAsStringAsync();

Console.WriteLine((int)res.StatusCode);
Console.WriteLine(body);

GET

/v1/listings/

require "net/http"
require "json"

token = ENV.fetch("TWENTYBAAN_API_KEY")
uri = URI("https://api.twentybaan.com/v1/listings/")
uri.query = URI.encode_www_form({ id: 123 })

req = Net::HTTP::Get.new(uri)
req["Accept"] = "application/json"
req["Authorization"] = "Bearer #{token}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(req)
end

puts res.code
puts res.body

GET

/v1/listings/

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
  "time"
)

func main() {
  token := os.Getenv("TWENTYBAAN_API_KEY")

  u, err := url.Parse("https://api.twentybaan.com/v1/listings/")
  if err != nil {
    panic(err)
  }

  q := u.Query()
  q.Set("id", "123")
  u.RawQuery = q.Encode()

  req, err := http.NewRequest("GET", u.String(), nil)
  if err != nil {
    panic(err)
  }

  req.Header.Set("Accept", "application/json")
  req.Header.Set("Authorization", "Bearer "+token)

  client := &http.Client{Timeout: 30 * time.Second}
  res, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  body, _ := io.ReadAll(res.Body)
  fmt.Println(res.Status)
  fmt.Println(string(body))
}

Response

{
  "ok": true,
  "listing": {
    "id": 123,
    "status": "published",
    "slug": "modern-condo-sukhumvit",
    "title": "Modern condo near BTS",
    "city": "Bangkok",
    "area": "Sukhumvit",
    "property_type": "condo",
    "offer_type": "rent",
    "rent_price_amount": 35000,
    "rent_price_period": "month",
    "sale_price_amount": null,
    "price_text": "฿35,000 / month",
    "beds_text": "2",
    "area_sqm": 62,
    "image_url": "https://...",
    "published_at": "2026-01-01T12:34:56Z",
    "created_at": "2025-12-15T09:12:00Z",
    "updated_at": "2026-01-02T03:45:00Z"
  }
}