Typeform

通过受管 OAuth 认证访问 Typeform API。创建和管理表单、获取响应数据，并访问洞察分析。

快速开始

# 列出表单
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/typeform/forms?page_size=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://api.maton.ai/typeform/{native-api-path}

Maton 将请求代理至 api.typeform.com，并自动注入您的 OAuth Token。

认证

所有请求均需在 Authorization 请求头中提供 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：请将您的 API 密钥设为 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 在 maton.ai 登录或注册账户
2. 访问 maton.ai/settings
3. 复制您的 API 密钥

连接管理

您可在 https://api.maton.ai 管理 Typeform 的 OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=typeform&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'typeform'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应示例：

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "typeform",
    "metadata": {}
  }
}

在浏览器中打开返回的 url，完成 OAuth 授权流程。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

若您拥有多个 Typeform 连接，请使用 Maton-Connection 请求头明确指定目标连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/typeform/forms?page_size=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

当存在多个连接时，务必始终包含该请求头，以确保请求被路由至预期账户。

安全与权限

• 访问范围限定于已连接的 Typeform 账户内的表单、响应、主题及工作区（workspace）。
• 所有写操作均需用户显式授权。 在执行任何创建、更新或删除调用前，须向用户确认目标资源及其预期影响。

API 参考

用户

GET /typeform/me

表单

列出表单

GET /typeform/forms?page_size=10

获取表单

GET /typeform/forms/{formId}

创建表单

POST /typeform/forms
Content-Type: application/json

{
  "title": "Customer Survey",
  "fields": [
    {"type": "short_text", "title": "What is your name?"},
    {"type": "email", "title": "What is your email?"}
  ]
}

更新表单

PUT /typeform/forms/{formId}
Content-Type: application/json

{
  "title": "Updated Survey Title",
  "fields": [...]
}

删除表单

DELETE /typeform/forms/{formId}

响应

列出响应

GET /typeform/forms/{formId}/responses?page_size=25

带过滤条件：

GET /typeform/forms/{formId}/responses?since=2024-01-01T00:00:00Z&until=2024-12-31T23:59:59Z&completed=true

洞察分析

GET /typeform/insights/{formId}/summary

工作区

GET /typeform/workspaces
GET /typeform/workspaces/{workspaceId}

字段类型

• short_text — 单行文本
• long_text — 多行文本
• email — 邮箱地址
• number — 数值输入
• rating — 星级评分
• opinion_scale — 0–10 分量表
• multiple_choice — 单选或多选
• yes_no — 布尔值
• date — 日期选择器
• dropdown — 下拉选择

代码示例

JavaScript

const response = await fetch(
  'https://api.maton.ai/typeform/forms?page_size=10',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

import os
import requests

response = requests.get(
    'https://api.maton.ai/typeform/forms',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'page_size': 10}
)

注意事项

• 表单 ID 为字母数字字符串
• 响应分页使用 before Token
• 时间戳采用 ISO 8601 格式
• DELETE 操作返回 HTTP 204
• 重要：使用 curl 命令时，若 URL 中包含方括号（如 fields[]、sort[]、records[]），请添加 curl -g 参数以禁用 glob 解析
• 重要：将 curl 输出管道传递给 jq 或其他命令时，在某些 Shell 环境中，$MATON_API_KEY 等环境变量可能无法正确展开，导致出现“Invalid API key”错误

错误处理

故障排查：API 密钥问题

1. 确认已设置 MATON_API_KEY 环境变量：

echo $MATON_API_KEY

2. 通过列出连接验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排查：应用名称无效

1. 确保您的 URL 路径以 typeform 开头。例如：

• 正确：https://api.maton.ai/typeform/forms
• 错误：https://api.maton.ai/forms

资源

• Typeform API 概览
• 表单
• 响应
• 工作区
• Maton 社区
• Maton 支持