Contact messages

List contact messages assigned to you, or retrieve a single message by id.

The contact message model

Contact messages are created when someone reaches out through a listing page or contact flow. The API returns messages that are assigned to the authenticated user (rep_user_id).

Properties

Name
id
Type
integer
Description
Unique identifier for the contact message.
Name
topic
Type
string|null
Description
Short subject/topic entered by the contact (when available).
Name
spot_name
Type
string|null
Description
Listing name (if the message came from a listing page).
Name
spot_slug
Type
string|null
Description
Listing slug (if the message came from a listing page).
Name
from_url
Type
string|null
Description
Page URL where the message was submitted.
Name
name
Type
string|null
Description
Contact name.
Name
email
Type
string|null
Description
Contact email address.
Name
phone
Type
string|null
Description
Contact phone number.
Name
move_in
Type
string|null
Description
Desired move-in date (free-form).
Name
budget
Type
string|null
Description
Budget (free-form).
Name
request_kind
Type
string|null
Description
Classification (for example viewing).
Name
request_status
Type
string|null
Description
Status for internal tracking (for example new, in_progress).
Name
preferred_slots
Type
array|null
Description
Preferred time slots (decoded from stored JSON when present).
Name
rep_user_id
Type
integer
Description
Assigned rep user id (used for filtering).
Name
created_at
Type
timestamp
Description
Timestamp of when the message was created.
Name
message
Type
string|null
Description
Full message text.

GET/v1/contact-messages/

List all contact messages

Retrieve a paginated list of contact messages that are assigned to the authenticated user. By default, a maximum of 50 messages are shown per page.

Optional attributes

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

Required scope

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

Request

GET

/v1/contact-messages/

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

GET

/v1/contact-messages/

const token = process.env.TWENTYBAAN_API_KEY;

const url = new URL("https://api.twentybaan.com/v1/contact-messages/");
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/contact-messages/

type TwentybaanContactMessagesResponse =
  | { 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/contact-messages/");
url.searchParams.set("limit", "10");

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

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

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

console.log(data.items);

GET

/v1/contact-messages/

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

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

GET

/v1/contact-messages/

<?php

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

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

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/contact-messages/?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/contact-messages/

require "net/http"
require "json"

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

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/contact-messages/")
  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,
      "topic": "Viewing request",
      "spot_name": "Twentybaan listing",
      "spot_slug": "modern-condo-sukhumvit",
      "from_url": "https://twentybaan.com/spots/modern-condo-sukhumvit/",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+66 12 345 6789",
      "move_in": "2026-02-01",
      "budget": "35000",
      "notes": "Can we do a viewing this week?",
      "request_kind": "viewing",
      "request_status": "new",
      "request_timezone": "Asia/Bangkok",
      "preferred_slots": [
        {"date": "2026-01-15", "time": "10:00"},
        {"date": "2026-01-16", "time": "14:00"}
      ],
      "rep_name": "Your Name",
      "rep_brand": "twentybaan",
      "rep_user_id": 42,
      "rep_email": "rep@twentybaan.com",
      "created_at": "2026-01-12T02:03:04Z",
      "message": "Hello, I'm interested in this property..."
    }
  ],
  "next_before_id": 120
}

GET/v1/contact-messages?id=:id

Retrieve a contact message

Fetch a single contact message by id. The authenticated user must be the assigned rep.

Required attributes

Name
id
Type
integer
Description
The contact message id to retrieve.

Errors

Returns 404 if the message does not exist or is not assigned to the authenticated user.

Request

GET

/v1/contact-messages/

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

GET

/v1/contact-messages/

const token = process.env.TWENTYBAAN_API_KEY;

const url = new URL("https://api.twentybaan.com/v1/contact-messages/");
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/contact-messages/

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

const token = process.env.TWENTYBAAN_API_KEY!;

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

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

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

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

console.log(data.contact_message);

GET

/v1/contact-messages/

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

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

GET

/v1/contact-messages/

<?php

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

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

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/contact-messages/?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/contact-messages/

require "net/http"
require "json"

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

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/contact-messages/")
  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,
  "contact_message": {
    "id": 123,
    "topic": "Viewing request",
    "spot_name": "Twentybaan listing",
    "spot_slug": "modern-condo-sukhumvit",
    "from_url": "https://twentybaan.com/spots/modern-condo-sukhumvit/",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+66 12 345 6789",
    "move_in": "2026-02-01",
    "budget": "35000",
    "notes": "Can we do a viewing this week?",
    "request_kind": "viewing",
    "request_status": "new",
    "request_timezone": "Asia/Bangkok",
    "preferred_slots": [
      {"date": "2026-01-15", "time": "10:00"},
      {"date": "2026-01-16", "time": "14:00"}
    ],
    "rep_name": "Your Name",
    "rep_brand": "twentybaan",
    "rep_user_id": 42,
    "rep_email": "rep@twentybaan.com",
    "created_at": "2026-01-12T02:03:04Z",
    "message": "Hello, I'm interested in this property..."
  }
}