Unformal API 技能

创建由AI驱动的对话流程（Pulses），用于替代表单、调查和接收邮件。向某人发送一个链接——AI代理会与他们进行真实对话，并提取结构化数据。

设置 — 代理注册（无需浏览器）

通过一次API调用即可创建账户、获取API密钥并开始创建Pulses：

bash
curl -X POST https://unformal.ai/api/v1/signup \
-H Content-Type: application/json \
-d {email: agent@company.com}

响应：
json
{
data: {
apikey: unfxxxxxxxxxxxxx,
workspace_id: ks7...,
email: agent@company.com,
credits: 50
}
}

API密钥仅显示一次。请安全存储。该端点无需身份验证。

替代方案：手动设置

1. 1. 访问 unformal.ai/studio/settings
2. 点击创建API密钥
3. 复制密钥（以 unf 开头）
4. 安全存储（仅显示一次）

基础URL： https://unformal.ai/api/v1

身份验证： 每次请求（除 /signup 外的所有端点）均需包含 Authorization: Bearer unfYOURKEY。

快速开始

创建一个Pulse并获取可分享的链接

bash
curl -X POST https://unformal.ai/api/v1/pulses \
-H Authorization: Bearer unfYOURKEY \
-H Content-Type: application/json \
-d {
intention: 了解新客户在我们首次会面前的需求
}

响应：
json
{
data: {
id: pls_abc123,
url: https://unformal.ai/p/understand-what-a-new-client-needs-a1b2c3,
slug: understand-what-a-new-client-needs-a1b2c3,
status: active
}
}

将URL发送给任何人。AI进行对话。你将获得结构化数据。

端点

注册（无需身份验证）

POST /signup

请求体：

响应（201）：
json
{
data: {
apikey: unfxxxxxxxxxxxxx,
workspace_id: ks7...,
email: agent@company.com,
credits: 50
}
}

如果邮箱已注册，返回 409 CONFLICT。

创建一个Pulse

POST /pulses

请求体：

最小示例：
json
{ intention: 评估此潜在客户是否符合我们的企业方案 }

完整示例：
json
{
intention: 了解每位团队成员的动机及需要支持的地方,
context: 我们是一个15人的初创公司。这是我们的季度团队检查。,
tone: coaching,
maxQuestions: 10,
linkType: multi,
showInsights: true,
webhookUrl: https://your-app.com/webhooks/unformal,
notifyEmail: hr@company.com
}

列出Pulses

GET /pulses

获取单个Pulse

GET /pulses/:id

更新Pulse

PATCH /pulses/:id

归档Pulse

DELETE /pulses/:id

发布Pulse

POST /pulses/:id/publish

列出Pulse的对话

GET /pulses/:id/conversations

返回所有对话的状态、echo（结构化数据）和元数据。

获取单个对话

GET /conversations/:id

返回完整对话：转录文本、echo（包含摘要、关键引述、潜台词、情感倾向的结构化数据）和元数据。

Echo示例：
json
{
echo: {
fields: {
budget_range: $50k-100k,
timeline: Q3 2026,
current_tools: [Salesforce, HubSpot],
decision_makers: [CTO, VP Sales]
},
summary: 非常适合企业方案。预算匹配，时间线为Q3。,
keyQuotes: [
我们每天花3小时进行手动数据录入,
CTO需要看到它能与我们的技术栈配合工作
],
subtext: 热情但担心内部支持不足。,
sentimentScore: 7
}
}

检查使用情况

GET /usage

返回积分余额和使用统计。

Webhooks

当Pulse设置了 webhookUrl 时，每次对话完成后Unformal会发送POST请求：

json
{
event: conversation.completed,
conversationId: conv_123,
pulseId: pls_456,
slug: your-pulse-slug,
echo: { ... },
completedAt: 2026-03-29T10:00:00Z,
transcriptSummary: ...
}

签名： X-Unformal-Signature 头部包含用于验证负载的HMAC-SHA256签名。

错误处理

所有错误遵循以下格式：
json
{
error: {
code: NOT_FOUND,
message: Pulse未找到
}
}

常见模式

代理为每个新潜在客户创建Pulse

当新潜在客户到达时：

1. 1. POST /pulses，intention为评估此潜在客户是否符合{产品}
2. 获取返回的URL
3. 通过邮件/短信将URL发送给潜在客户
4. 等待包含Echo数据的webhook
5. 使用结构化评估数据更新CRM

跨用户的批量调研

1. 1. POST /pulses，linkType设为multi
2. 将同一URL发送给50个用户
3. GET /pulses/:id/conversations 查看所有响应
4. 3次以上对话后自动计算共振（在Studio中可见）

针对特定人员的单次接收

1. 1. POST /pulses，linkType设为single
2. 将URL发送给该特定人员
3. 他们回复后链接失效
4. GET /conversations/:id 获取完整Echo

速率限制

• - 免费版：每分钟100次请求
• 付费版：每分钟1000次请求

积分

• - 每次完成的对话消耗1积分
• allowResearch: true 每次对话消耗2积分
• 免费：注册时获得50积分