JotForm

通过受管的 OAuth 认证访问 JotForm API。创建和管理表单、获取提交数据，以及管理 Webhook。

快速开始

# 列出用户表单
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/jotform/user/forms?limit=20')
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/jotform/{native-api-path}

Maton 将请求代理至 api.jotform.com，并自动注入您的 API 密钥。

认证

所有请求均需在 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 管理您的 JotForm 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=jotform&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': 'jotform'}).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": "jotform",
    "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

指定连接

若您拥有多个 JotForm 连接，请使用 Maton-Connection 请求头指定要使用的连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/jotform/user/forms')
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

若存在多个连接，务必始终包含该请求头，以确保请求被路由至目标账户。

安全与权限

• 访问范围限定于已连接 JotForm 账户内的表单、提交数据及表单元数据。
• 所有写入操作均需显式用户授权。 在执行任何创建（create）、更新（update）或删除（delete）调用前，必须向用户确认目标资源及其预期影响。

API 参考文档

用户

GET /jotform/user
GET /jotform/user/forms?limit=20
GET /jotform/user/submissions?limit=20
GET /jotform/user/usage

表单

获取表单

GET /jotform/form/{formId}

获取表单问题

GET /jotform/form/{formId}/questions

获取表单提交数据

GET /jotform/form/{formId}/submissions?limit=20

带过滤器：

GET /jotform/form/{formId}/submissions?filter={"created_at:gt":"2024-01-01"}

创建表单

POST /jotform/user/forms
Content-Type: application/json

{
  "properties": {"title": "Contact Form"},
  "questions": {
    "1": {"type": "control_textbox", "text": "Name", "name": "name"},
    "2": {"type": "control_email", "text": "Email", "name": "email"}
  }
}

删除表单

DELETE /jotform/form/{formId}

提交数据

获取提交记录

GET /jotform/submission/{submissionId}

删除提交记录

DELETE /jotform/submission/{submissionId}

Webhook

GET /jotform/form/{formId}/webhooks
POST /jotform/form/{formId}/webhooks
DELETE /jotform/form/{formId}/webhooks/{webhookIndex}

问题类型

• control_textbox — 单行文本
• control_textarea — 多行文本
• control_email — 邮箱
• control_phone — 电话号码
• control_dropdown — 下拉菜单
• control_radio — 单选按钮
• control_checkbox — 复选框
• control_datetime — 日期/时间选择器
• control_fileupload — 文件上传

过滤器语法

{"field:gt":"value"}  // 大于
{"field:lt":"value"}  // 小于
{"field:eq":"value"}  // 等于

代码示例

JavaScript

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

Python

import os
import requests

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

注意事项

• 表单 ID 为数值型
• 分页使用 limit 和 offset
• 使用 orderby 对结果进行排序
• 重要：当使用 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 路径以 jotform 开头。例如：

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

相关资源

• JotForm API 概览
• 用户表单
• 表单提交数据
• Webhook
• Maton 社区
• Maton 支持