API

用 API key 建立問卷與具名對象。API 不會寄信——寄邀請請用後台。

到 設定 → API keys 建立金鑰。請求頭：Authorization: Bearer <key>。

環境變數名：WHEREGOING_API_KEY（別名 WHEREGOING_TOKEN）。

Base URL：https://wheregoing.com/api/v1

路徑裡的 {id} 可用問卷 id 或 slug。

API 不會寄信。每位對象的回傳裡都有 url。要寄邀請請到後台「寄送對象」。預設語系路徑是 /s/{slug}/{recipientId}；中文頁是 /zh/s/{slug}/{recipientId}。

建立問卷

curl -X POST https://wheregoing.com/api/v1/surveys \
  -H "Authorization: Bearer $WHEREGOING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetCompany": "達友科技",
    "title": "想向達友請教這段真實經驗",
    "description": "約 3 分鐘的研究問卷。沒有標準答案，依照實際發生的情況回答即可。",
    "questions": [
      {
        "type": "multiple_choice",
        "label": "目前客戶資料主要存放在哪些地方？",
        "required": true,
        "options": ["多份 Excel／CSV", "ERP", "CRM", "Google 試算表"],
        "allowOther": true
      },
      {
        "type": "linear_scale",
        "label": "整理這些資料現在有多痛苦？",
        "required": true,
        "scaleMin": 1,
        "scaleMax": 10,
        "scaleMinLabel": "還好",
        "scaleMaxLabel": "做不下去"
      }
    ],
    "recipients": [
      {
        "targetCompany": "達友科技",
        "email": "[email protected]",
        "title": "想向達友請教這段真實經驗",
        "accentColor": "#315c4c"
      }
    ]
  }'

回傳的 survey.recipients[].url 就是這個人的專屬公開頁。

列出與讀取

curl https://wheregoing.com/api/v1/surveys \
  -H "Authorization: Bearer $WHEREGOING_API_KEY"

curl https://wheregoing.com/api/v1/surveys/{id} \
  -H "Authorization: Bearer $WHEREGOING_API_KEY"

更新問卷

PATCH /api/v1/surveys/{id}，可帶 title、description、welcomeMessage、logoUrl、accentColor、questions、recipients 的任一子集。

若帶上 recipients 會整份覆寫。要在不丟掉現有對象的前提下加人，用下面的端點。

建立時可選：slug、published、notifyOnResponse、notificationEmail。邀請文案寫在各收件人上（inviteTop、inviteBottom、inviteSignOff）。slug 重複回 409。

新增對象

curl -X POST https://wheregoing.com/api/v1/surveys/{id}/recipients \
  -H "Authorization: Bearer $WHEREGOING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skipExisting": true,
    "recipients": [
      { "targetCompany": "北風貿易", "email": "[email protected]" }
    ]
  }'

以 id 或 email 比對。預設是 upsert。skipExisting: true 時略過已存在的列（保住 inviteSentAt）。回傳含 added、updated、skipped。每份問卷最多 200 人。

讀回覆

curl https://wheregoing.com/api/v1/surveys/{id}/responses \
  -H "Authorization: Bearer $WHEREGOING_API_KEY"

題型

short_text、long_text、single_choice、multiple_choice、dropdown、linear_scale、rating、multiple_choice_grid、checkbox_grid、date、time。

選擇題用 options。線性刻度：scaleMin 只能 0 或 1，scaleMax 2–10。

錯誤

狀態	意思
401	缺少或無效的 API key
400	內容驗證失敗（`details` 來自 Zod）
404	這個 key 找不到該問卷
409	`slug` 已被使用
429	API key 超過速率限制

可直接貼給 agent 的提示詞見agent 頁。

API