資料看板

client.boards 是 CRM 管道的核心資料儲存 — 潛在客戶、交易、任務或任何結構化資料。每個 board 都有自訂欄位和項目。Board 也可以連結到 Knowledge Hub 以進行 AI 驅動的搜尋。

結構定義

Board

欄位	類型	說明
`object_name`	string?	物件類型識別碼
`id`	string	唯一的 board ID
`organization_id`	string	所屬組織
`name`	string	Board 顯示名稱
`description`	string?	選用說明
`workflow_id`	string?	連結的 workflow ID
`hidden`	boolean?	Board 是否隱藏
`team_ids`	string[]?	有存取權限的團隊
`created_at`	string	ISO 8601 建立時間戳
`updated_at`	string	ISO 8601 更新時間戳

BoardField

欄位	類型	說明
`_id`	string	唯一的欄位 ID
`name`	string	欄位顯示名稱
`type`	string	欄位類型（text, number, date, select 等）
`options`	object[]?	類型特定設定
`required`	boolean?	欄位是否為必填

CreateBoardInput

欄位	類型	必填	說明
`name`	string	✓	Board 名稱
`description`	string		選用說明
`type`	string		Board 類型
`fields`	object[]		初始欄位定義
`team_ids`	string[]		有存取權限的團隊 ID
`show_id`	boolean		顯示 ID 欄

方法

Board CRUD

方法	TypeScript	Python	說明
列出 boards	`list`	`list`	列出所有 board
取得 board	`get`	`get`	依 ID 取得 board
建立 board	`create`	`create`	建立新 board
更新 board	`update`	`update`	更新 board 名稱/說明
刪除 board	`delete`	`delete`	刪除 board
重新排序 boards	`reorder`	`reorder`	變更顯示順序

匯入 / 匯出

方法	TypeScript	Python	說明
匯出 CSV	`exportCsv`	`export_csv`	將所有項目匯出為 CSV
匯入 CSV	`importCsv`	`import_csv`	從 CSV 檔案匯入項目
匯入 Excel	`importExcel`	`import_excel`	從 Excel 檔案匯入項目
取得匯入進度	`getImportProgress`	`get_import_progress`	輪詢進行中匯入的狀態

欄位

方法	TypeScript	Python	說明
建立欄位	`createField`	`create_field`	向 board 新增欄位
更新欄位	`updateField`	`update_field`	修改欄位設定
刪除欄位	`deleteField`	`delete_field`	移除欄位
重新排序欄位	`reorderFields`	`reorder_fields`	變更欄位順序
批次更新欄位	`bulkUpdateFields`	`bulk_update_fields`	同時更新多個欄位

項目

方法	TypeScript	Python	說明
列出項目	`listItems`	`list_items`	分頁的 board 項目列表
取得項目	`getItem`	`get_item`	取得單一項目
建立項目	`createItem`	`create_item`	向 board 新增項目
更新項目	`updateItem`	`update_item`	更新項目欄位值
刪除項目	`deleteItem`	`delete_item`	移除項目
批次刪除	`bulkDeleteItems`	`bulk_delete_items`	依 ID 刪除多個項目
搜尋	`search`	`search`	在 board 內進行全文搜尋
連結項目	`linkItems`	`link_items`	將項目連結到相關 board 項目
取消連結項目	`unlinkItems`	`unlink_items`	移除項目間的連結

區隔

方法	TypeScript	Python	說明
列出區隔	`listSegments`	`list_segments`	列出已儲存的篩選檢視
建立區隔	`createSegment`	`create_segment`	將篩選條件儲存為區隔
更新區隔	`updateSegment`	`update_segment`	更新區隔的篩選條件
刪除區隔	`deleteSegment`	`delete_segment`	移除區隔

const { data: boards } = await client.boards.list({ limit: 20 });
for (const board of boards) {
  console.log(board.id, board.name);
}

result = client.boards.list(limit=20)
for board in result.get("data", []):
    print(board["id"], board["name"])

create / create

TypeScript
Python

const board = await client.boards.create({
  name: "Enterprise Leads",
  description: "Leads from the enterprise segment",
  fields: [
    { name: "Company", type: "text" },
    { name: "Deal Size", type: "number" },
    { name: "Stage", type: "select", options: { choices: ["Prospect", "Qualified", "Closed"] } },
  ],
});

board = client.boards.create(
    "Enterprise Leads",
    description="Leads from the enterprise segment",
    fields=[
        {"name": "Company", "type": "text"},
        {"name": "Deal Size", "type": "number"},
        {"name": "Stage", "type": "select", "options": {"choices": ["Prospect", "Qualified", "Closed"]}},
    ],
)

createItem / create_item

傳遞一個 fields 陣列，其中每個條目都有 board_field_id（BoardField 的 _id）和對應的 value。

TypeScript
Python

const item = await client.boards.createItem("board_id", {
  fields: [
    { board_field_id: "field_id_company", value: "Acme Corp" },
    { board_field_id: "field_id_deal_size", value: 50000 },
    { board_field_id: "field_id_stage", value: "Qualified" },
  ],
});

item = client.boards.create_item("board_id", {
    "fields": [
        {"board_field_id": "field_id_company", "value": "Acme Corp"},
        {"board_field_id": "field_id_deal_size", "value": 50000},
        {"board_field_id": "field_id_stage", "value": "Qualified"},
    ],
})

listItems / list_items

TypeScript
Python

const page = await client.boards.listItems("board_id", { limit: 50, skip: 0 });
console.log(`${page.data.length} of ${page.total} items`);

page = client.boards.list_items("board_id", limit=50, skip=0)
print(f"{len(page['data'])} of {page['total']} items")

search

在 board 的項目中進行全文搜尋。

TypeScript
Python

const results = await client.boards.search("board_id", {
  q: "Acme",
  limit: 20,
  offset: 0,
});

results = client.boards.search("board_id", q="Acme", limit=20, offset=0)

importCsv / import_csv

TypeScript
Python

const formData = new FormData();
formData.append("file", csvBlob, "leads.csv");
const result = await client.boards.importCsv("board_id", formData);
console.log(`Imported: ${result.imported}, Errors: ${result.errors}`);

with open("leads.csv", "rb") as f:
    result = client.boards.import_csv("board_id", files={"file": f})
print(result)

createField / create_field

TypeScript
Python

const field = await client.boards.createField("board_id", {
  name: "Priority",
  type: "select",
  options: { choices: ["Low", "Medium", "High"] },
});

field = client.boards.create_field("board_id", {
    "name": "Priority",
    "type": "select",
    "options": {"choices": ["Low", "Medium", "High"]},
})