Contracts

Contracts are the container for rental/sale workflows. These endpoints let you read contract summaries from external tools.

Last updated:

The contract model

Contracts can be in different statuses (for example draft, active, ended). The exact flow depends on your account.

Properties

Name

id

Type

integer

Description

Unique identifier for the contract.
Name

listing_id

Type

integer | null

Description

Listing id associated with the contract (if any).
Name

kind

Type

string

Description

Contract kind (rent, sale, etc.).
Name

status

Type

string

Description

Current status of the contract.
Name

created_at

Type

timestamp

Description

Timestamp of when the contract was created.
Name

updated_at

Type

timestamp

Description

Timestamp of the last contract update.

GET/v1/contracts/

List contracts

This endpoint returns a paginated list of contract summaries.

Required scope

read:contracts

Request

GET

/v1/contracts/

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

GET

/v1/contracts/

const token = process.env.TWENTYBAAN_API_KEY;

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

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

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

GET

/v1/contracts/

type TwentybaanContract = {
  id: number;
  listing_id: number | null;
  unit_id: number | null;
  kind: string;
  status: string;
  unit_label: string | null;
  template_id: number | null;
  created_at: string;
  updated_at: string;
  listing: {
    id: number;
    slug: string;
    title: string;
    city: string;
    area: string;
  } | null;
};

type TwentybaanContractsResponse =
  | { ok: true; items: TwentybaanContract[]; 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/contracts/");
url.searchParams.set("limit", "10");

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

const data = (await res.json()) as TwentybaanContractsResponse;
if (!res.ok || !data.ok) throw new Error("Request failed");

console.log(data.items);

GET

/v1/contracts/

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

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

GET

/v1/contracts/

<?php

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

$url = "https://api.twentybaan.com/v1/contracts/" . '?' . 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/contracts/

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/contracts/?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/contracts/

require "net/http"
require "json"

token = ENV.fetch("TWENTYBAAN_API_KEY")
uri = URI("https://api.twentybaan.com/v1/contracts/")
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/contracts/

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/contracts/")
  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,
      "listing_id": 42,
      "unit_id": null,
      "kind": "rent",
      "status": "draft",
      "unit_label": "Unit 12A",
      "template_id": 7,
      "created_at": "2026-01-12T08:00:00Z",
      "updated_at": "2026-01-12T09:10:00Z",
      "listing": {
        "id": 42,
        "slug": "nice-apartment-bangkok",
        "title": "Nice apartment",
        "city": "Bangkok",
        "area": "Sukhumvit"
      }
    }
  ],
  "next_before_id": null
}

GET/v1/contracts/?id=:id

Retrieve a contract

Fetch a contract by id.

To include the contract data payload, pass include_data=1.

Required scope

read:contracts

Request

GET

/v1/contracts/?id=123

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

GET

/v1/contracts/?id=123

const token = process.env.TWENTYBAAN_API_KEY;

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

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

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

GET

/v1/contracts/?id=123

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

const token = process.env.TWENTYBAAN_API_KEY!;

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

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

const data = (await res.json()) as TwentybaanContractResponse;
if (!res.ok || !data.ok) throw new Error("Request failed");

console.log(data.contract);

GET

/v1/contracts/?id=123

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

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

GET

/v1/contracts/?id=123

<?php

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

$url = "https://api.twentybaan.com/v1/contracts/" . '?' . 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/contracts/?id=123

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/contracts/?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/contracts/?id=123

require "net/http"
require "json"

token = ENV.fetch("TWENTYBAAN_API_KEY")
uri = URI("https://api.twentybaan.com/v1/contracts/")
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/contracts/?id=123

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/contracts/")
  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,
  "contract": {
    "id": 123,
    "listing_id": 42,
    "unit_id": null,
    "kind": "rent",
    "status": "draft",
    "unit_label": "Unit 12A",
    "template_id": 7,
    "created_at": "2026-01-12T08:00:00Z",
    "updated_at": "2026-01-12T09:10:00Z",
    "listing": {
      "id": 42,
      "slug": "nice-apartment-bangkok",
      "title": "Nice apartment",
      "city": "Bangkok",
      "area": "Sukhumvit"
    }
  }
}