Formilly

REST API

最後更新：2026 年 9 月 14 日

把表單回覆拉進你自己的系統。專業版與企業版適用，service@formilly.com 收技術問題。

取得金鑰

登入後台 →「API」→ 建立金鑰。明文只會出現一次，關掉視窗就再也調不出來——我們資料庫裡只存雜湊，連我們自己都還原不了。弄丟就撤銷舊的再開一把。

金鑰能讀取整個工作區的所有回覆，也能刪除回覆。不要放進前端程式碼或公開的 repo，只放在你自己的伺服器環境變數裡。

一個工作區最多同時保有 5 把。建議一個用途一把，這樣要停掉哪個整合時不會影響其他的。

認證

每個請求都要帶金鑰。兩種寫法都可以，後者是給沒辦法自訂 Authorization 標頭的工具用的（例如某些 no-code 平台）。

curl https://formilly.com/v1/forms \
  -H "Authorization: Bearer fmly_你的金鑰"

curl https://formilly.com/v1/forms \
  -H "X-API-Key: fmly_你的金鑰"

端點

方法與路徑	說明
`GET /v1/forms`	列出工作區的表單，依最後更新時間排序
`GET /v1/forms/{id}`	單一表單，含所有題目定義（跨版本合併）
`GET /v1/forms/{id}/responses`	該表單的回覆，新的在前
`GET /v1/responses/{id}`	單筆回覆
`DELETE /v1/responses/{id}`	刪除單筆回覆。用於個資法的當事人刪除請求

分頁

回覆列表用游標分頁，不是 offset。回覆會一直進來，用 ?page=2 這種寫法在翻頁途中會漏掉資料——對定時同步來說那是最難察覺的錯誤。

limit 預設 25、最大 100。回應裡的 next_cursor 直接帶回去就是下一頁；has_more 為 false 時 next_cursor 是 null。

# 第一頁
curl "https://formilly.com/v1/forms/FORM_ID/responses?limit=50" \
  -H "Authorization: Bearer $FORMILLY_KEY"

# 下一頁：把上一頁的 next_cursor 帶回來
curl "https://formilly.com/v1/forms/FORM_ID/responses?limit=50&cursor=MjAyNi0..." \
  -H "Authorization: Bearer $FORMILLY_KEY"

回應格式

每個答案同時給 value 與 raw。value 是人看的字串（選項會換成標籤文字），raw 是原始值（選項是 id、多選是陣列、矩陣是物件）。要寫進試算表用前者，要程式判斷選了哪一項用後者。

{
  "data": [
    {
      "id": "5febe821-23ab-43f7-b920-04b777c1323b",
      "submitted_at": "2026-09-14T05:00:55.358Z",
      "duration_ms": 42117,
      "line_user_id": null,
      "answers": {
        "tjfki8p2": { "label": "姓名",   "type": "short_text",    "value": "王小明", "raw": "王小明" },
        "u4xibv7g": { "label": "場次",   "type": "single_choice", "value": "上午場", "raw": "o1" },
        "8s7et6g2": { "label": "餐食",   "type": "multi_choice",  "value": "素食、不吃牛", "raw": ["o2", "o3"] }
      }
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOS0xNFQwNTowMDo1NS4zNTha..."
}

錯誤

錯誤一律是 HTTP 4xx／5xx，內容形狀固定：{ "error": { "code": "...", "message": "..." } }。判斷請看 code，message 的文字可能會調整。

狀態	code	意思
401	`unauthorized`	沒帶金鑰、格式不對、金鑰無效或已撤銷
403	`plan_required`	工作區目前不是專業版或企業版
404	`not_found`	找不到，或那筆資料不屬於這把金鑰的工作區
400	`invalid_cursor`	游標格式錯誤，請直接帶回上一頁的 `next_cursor`
429	`rate_limited`	超過每分鐘 120 次，等 60 秒再試

頻率限制

每把金鑰每分鐘 120 次。超過會回 429 並附上 Retry-After: 60。

要一次拉很多資料的話，把 limit 開到 100 比縮短間隔有效得多——同樣的資料量，請求次數少四倍。

要即時而不是輪詢的話

如果你的需求是「有人填了就馬上處理」，用 Webhook 比用這個 API 輪詢好：收到回覆的當下就 POST 到你的網址，附 HMAC-SHA256 簽章，失敗會自動重試。設定在後台每張表單的「Webhook」分頁。

這個 API 適合的是對帳、補跑、把歷史資料一次匯入，以及刪除請求。

版本

路徑裡的 v1 就是承諾：這一版的欄位不會被移除或改變意義。新增欄位不算破壞性變更，所以你的程式碼不應該假設回應裡只有目前這些欄位。

真的需要不相容的變更時會開 v2，v1 會保留至少 12 個月，並事先寄信通知有在使用的工作區。