Cognito Forms

通过托管的 OAuth 认证访问 Cognito Forms API。可列出表单、管理条目（创建、读取、更新、删除）以及检索文档。

快速开始

# List all forms
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/cognito-forms/api/forms')
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://gateway.maton.ai/cognito-forms/{native-api-path}

将{native-api-path}替换为实际的 Cognito Forms API 端点路径（以api/开头）。网关会将请求代理到www.cognitoforms.com并自动注入您的 OAuth 令牌。

认证

所有请求都需要在 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密钥

连接管理

请在以下位置管理您的Cognito Forms OAuth连接https://ctrl.maton.ai。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=cognito-forms&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': 'cognito-forms'}).encode()
req = urllib.request.Request('https://ctrl.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://ctrl.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": "77de1a60-5f69-45fc-977c-9dfffe7a64d4",
    "status": "ACTIVE",
    "creation_time": "2026-02-08T10:39:10.245446Z",
    "last_updated_time": "2026-02-09T04:11:08.342101Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "cognito-forms",
    "metadata": {}
  }
}

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

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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

指定连接

如果您有多个Cognito Forms连接，请使用Maton-Connection标头指定要使用的连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/cognito-forms/api/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '77de1a60-5f69-45fc-977c-9dfffe7a64d4')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早的）活动连接。

API参考

表单

列出表单

GET /cognito-forms/api/forms

返回组织中的所有表单。

条目

获取条目

GET /cognito-forms/api/forms/{formId}/entries/{entryId}

通过ID或条目编号返回特定条目。

创建条目

POST /cognito-forms/api/forms/{formId}/entries
Content-Type: application/json

{
  "Name": {
    "First": "John",
    "Last": "Doe"
  },
  "Email": "john.doe@example.com",
  "Phone": "555-1234"
}

字段名称与您表单中的字段名称匹配。复杂字段（如姓名和地址）使用嵌套对象。

更新条目

PATCH /cognito-forms/api/forms/{formId}/entries/{entryId}
Content-Type: application/json

{
  "Name": {
    "First": "Jane",
    "Last": "Doe"
  },
  "Email": "jane.doe@example.com"
}

更新现有条目。使用PATCH方法（非PUT）。如果条目包含已付款订单，操作将失败。

删除条目

DELETE /cognito-forms/api/forms/{formId}/entries/{entryId}

删除条目。需要读取/写入/删除API权限范围。

文档

获取文档

GET /cognito-forms/api/forms/{formId}/entries/{entryId}/documents/{templateNumber}

使用指定的模板编号，从条目生成并返回文档。

响应：

{
  "Id": "abc123",
  "Name": "Entry-Document.pdf",
  "ContentType": "application/pdf",
  "Size": 12345,
  "File": "https://temporary-download-url..."
}

文件

获取文件

GET /cognito-forms/api/files/{fileId}

检索上传到表单条目的文件。

响应：

{
  "Id": "file-id",
  "Name": "upload.pdf",
  "ContentType": "application/pdf",
  "Size": 54321,
  "File": "https://temporary-download-url..."
}

字段格式示例

姓名字段

{
  "Name": {
    "First": "John",
    "Last": "Doe"
  }
}

地址字段

{
  "Address": {
    "Line1": "123 Main St",
    "Line2": "Suite 100",
    "City": "San Francisco",
    "State": "CA",
    "PostalCode": "94105"
  }
}

选择字段

单选：

{
  "PreferredContact": "Email"
}

多选：

{
  "Interests": ["Sports", "Music", "Travel"]
}

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/cognito-forms/api/forms',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const forms = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/cognito-forms/api/forms',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
forms = response.json()

创建条目示例 (Python)

import os
import requests

entry_data = {
    "Name": {"First": "John", "Last": "Doe"},
    "Email": "john@example.com",
    "Message": "Hello from the API!"
}

response = requests.post(
    'https://gateway.maton.ai/cognito-forms/api/forms/ContactForm/entries',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json=entry_data
)

注意事项

• 列出条目：Cognito Forms API 不支持批量列出所有条目。请使用 Webhooks 或 OData 来同步条目。
• 获取表单：返回 404 错误 - 请改用"列出表单"来获取表单信息。
• 表单可用性：此端点可能不可用，具体取决于您的 Cognito Forms 套餐。
• 条目 ID 可以是条目编号或条目 ID (格式：{表单ID}-{条目编号})
• 复杂字段（如姓名、地址）使用嵌套的 JSON 对象
• 文件上传会返回临时的下载 URL
• 文档生成功能可根据表单模板创建 PDF
• API 作用域控制访问权限：读取、读/写或读/写/删除
• 重要提示：使用 curl 命令时，如果 URL 包含方括号，请使用curl -g以禁用通配符解析
• 重要提示：将 curl 输出通过管道传递给jq或其他命令中，环境变量如$MATON_API_KEY在某些shell环境中可能无法正确展开

错误处理

故障排除：API密钥问题

1. 检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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路径以cognito-forms开头。例如：

• 正确示例：https://gateway.maton.ai/cognito-forms/api/forms
• 错误示例：https://gateway.maton.ai/api/forms

资源

• Cognito Forms API 概览
• REST API 参考
• API 参考
• Maton 社区
• Maton 支持