团队 API

管理团队、成员、角色和邀请，实现协作表单构建。

团队 API 允许您创建和管理协作表单构建的团队。团队允许多个用户共享表单，通过基于角色的访问控制管理谁可以查看、编辑和删除表单及响应。

所有请求和响应体均使用 snake_case 字段命名。

团队角色

ownerrole

完全访问权限。可以管理成员、账单和删除团队。

adminrole

可以创建、编辑、删除表单，管理成员和查看响应。

editorrole

可以创建和编辑表单，查看响应。无法管理成员。

viewerrole

可以查看表单和响应。无法创建或编辑。

Endpoints

GET/api/v1/teamsPOST/api/v1/teamsGET/api/v1/teams/:teamIdPUT/api/v1/teams/:teamIdDELETE/api/v1/teams/:teamIdGET/api/v1/teams/:teamId/membersPOST/api/v1/teams/:teamId/membersPUT/api/v1/teams/:teamId/members/:memberIdDELETE/api/v1/teams/:teamId/members/:memberIdGET/api/v1/teams/:teamId/invitationsPOST/api/v1/teams/:teamId/invitationsDELETE/api/v1/teams/:teamId/invitations/:invId

列出团队

GET/api/v1/teams

返回已认证用户所属的所有团队。

响应

json

{
  "teams": [
    {
      "id": "665b2c3d4e5f6a7b8c9d0e1f",
      "name": "Marketing",
      "slug": "marketing",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-01-10T09:00:00.000Z",
      "updated_at": "2026-02-15T11:30:00.000Z",
      "member_count": 5,
      "your_role": "admin"
    },
    {
      "id": "665c3d4e5f6a7b8c9d0e1f20",
      "name": "Product",
      "slug": "product",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-02-01T14:00:00.000Z",
      "updated_at": "2026-02-20T16:45:00.000Z",
      "member_count": 3,
      "your_role": "owner"
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

创建团队

POST/api/v1/teams

创建新团队。已认证用户将成为团队所有者。

请求体

namestring

团队名称

请求示例

json

{
  "name": "Marketing"
}

响应

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing" }'

获取团队

GET/api/v1/teams/:teamId

通过 ID 检索单个团队。

团队的任何成员都可以调用。响应中从不包含团队的机密信息（数据驻留数据库的连接字符串、SSO 连接 ID 或内部域名 ID），而 sso_domain_verify_token（用于证明 SSO 域名的 DNS 值）仅返回给具有 owner 或 admin 角色的调用者。

路径参数

teamIdstring

团队 ID

响应

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-02-15T11:30:00.000Z",
  "member_count": 5
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

更新团队

PUT/api/v1/teams/:teamId

更新团队属性。需要 owner 或 admin 角色。

路径参数

teamIdstring

团队 ID

请求体

namestring

新团队名称

请求示例

json

{
  "name": "Marketing & Growth"
}

代码示例

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing & Growth" }'

删除团队

DELETE/api/v1/teams/:teamId

永久删除团队。仅团队所有者可以删除团队。

删除团队将移除所有团队成员资格和邀请。属于该团队的表单不会被自动删除，但前团队成员将无法再访问。

路径参数

teamIdstring

团队 ID

响应

json

{
  "success": true
}

代码示例

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

列出成员

GET/api/v1/teams/:teamId/members

返回团队的所有成员。

路径参数

teamIdstring

团队 ID

响应

json

{
  "members": [
    {
      "id": "66d1e2f3a4b5c6d7e8f9a0b1",
      "user_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Johnson",
      "role": "owner",
      "joined_at": "2026-01-10T09:00:00.000Z"
    },
    {
      "id": "66d2e3f4a5b6c7d8e9f0a1b2",
      "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "email": "bob@example.com",
      "first_name": "Bob",
      "last_name": "Smith",
      "role": "editor",
      "joined_at": "2026-01-15T14:30:00.000Z"
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

通过邮箱邀请某人加入团队，与创建邀请完全相同：NueForm 会通过邮件发送邀请，邀请在 7 天后过期，对方接受后即加入团队。此接口不会直接添加现有用户。需要 owner 或 admin 角色。返回该邀请（201）；如果该地址已属于团队成员或已有尚未过期的待处理邀请，返回 409（已过期的邀请不会阻止发送新邀请）；如果团队所有者的套餐没有剩余席位，返回 400——待处理的邀请在过期前也会占用一个席位。

路径参数

teamIdstring

团队 ID

请求体

emailstring

要邀请的邮箱地址（以小写形式存储）

rolestring

对方接受后获得的角色："admin"、"editor" 或 "viewer"

请求示例

json

{
  "email": "carol@example.com",
  "role": "editor"
}

响应

json

{
  "id": "66e1f2a3b4c5d6e7f8a9b0c1",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "email": "carol@example.com",
  "role": "editor",
  "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
  "token": "2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f",
  "status": "pending",
  "language": "en",
  "expires_at": "2026-03-07T12:00:00.000Z",
  "created_at": "2026-02-28T12:00:00.000Z",
  "invite_url": "/teams/invite/2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carol@example.com",
    "role": "editor"
  }'

更新成员角色

PUT/api/v1/teams/:teamId/members/:memberId

更新团队成员的角色。需要 owner 或 admin 角色。无法更改所有者的角色。

路径参数

teamIdstring

团队 ID

memberIdstring

团队成员 ID

请求体

rolestring

新角色："admin"、"editor"、"viewer"

请求示例

json

{
  "role": "admin"
}

响应

json

{
  "id": "66d2e3f4a5b6c7d8e9f0a1b2",
  "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "role": "admin",
  "joined_at": "2026-01-15T14:30:00.000Z"
}

代码示例

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

移除成员

DELETE/api/v1/teams/:teamId/members/:memberId

从团队中移除成员。需要 owner 或 admin 角色。团队所有者不能被移除。该团队发给此人的待处理邀请也会被取消，因此对方无法凭这些邀请重新加入。

路径参数

teamIdstring

团队 ID

memberIdstring

团队成员 ID

响应

json

{
  "success": true,
  "message": "Member removed from team"
}

代码示例

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY"

列出邀请

GET/api/v1/teams/:teamId/invitations

返回团队中尚未过期的待处理邀请，最新的在前。团队的任何成员都可以调用；token 字段（邀请链接中的密钥）仅对具有 owner 或 admin 角色的调用者返回。

路径参数

teamIdstring

团队 ID

响应

json

{
  "invitations": [
    {
      "id": "66e1f2a3b4c5d6e7f8a9b0c1",
      "email": "carol@example.com",
      "role": "editor",
      "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "status": "pending",
      "expires_at": "2026-03-07T12:00:00.000Z",
      "created_at": "2026-02-28T12:00:00.000Z"
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY"

创建邀请

POST/api/v1/teams/:teamId/invitations

发送加入团队的邮件邀请。邀请包含唯一令牌，7 天后过期。需要 owner 或 admin 角色。如果该地址已属于团队成员或已有尚未过期的待处理邀请，返回 409（已过期的邀请不会阻止发送新邀请）；如果团队所有者的套餐没有剩余席位，返回 400——待处理的邀请在过期前也会占用一个席位。

路径参数

teamIdstring

团队 ID

请求体

emailstring

要邀请的邮箱地址

rolestring

对方接受后获得的角色："admin"、"editor" 或 "viewer"

请求示例

json

{
  "email": "carol@example.com",
  "role": "editor"
}

响应

json

{
  "id": "66e1f2a3b4c5d6e7f8a9b0c1",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "email": "carol@example.com",
  "role": "editor",
  "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
  "token": "2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f",
  "status": "pending",
  "language": "en",
  "expires_at": "2026-03-07T12:00:00.000Z",
  "created_at": "2026-02-28T12:00:00.000Z",
  "invite_url": "/teams/invite/2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carol@example.com",
    "role": "editor"
  }'

取消邀请

DELETE/api/v1/teams/:teamId/invitations/:invId

取消待处理的邀请。需要 owner 或 admin 角色。邀请令牌将不再有效。

路径参数

teamIdstring

团队 ID

invIdstring

邀请 ID

响应

json

{
  "success": true,
  "message": "Invitation cancelled"
}

代码示例

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations/66e1f2a3b4c5d6e7f8a9b0c1" \
  -H "Authorization: Bearer YOUR_API_KEY"

错误响应

团队 API 端点返回的标准错误响应。

错误码

400Bad Request

缺少必填字段、邮箱或角色无效，或团队所有者的套餐已没有剩余席位

401Unauthorized

缺少或无效的 API 密钥

403Forbidden

不是团队成员，或角色权限不足

404Not Found

团队、成员或邀请未找到

409Conflict

用户已是成员，重复邀请

500Server Error

服务器内部错误

错误示例

json

{
  "error": {
    "code": "CONFLICT",
    "message": "A pending invitation already exists for this email",
    "status": 409
  }
}

最后更新：2026年10月8日