为你的寄样数据打造的达人 API。

API 是用来做什么的

它面向想把 Pozto 的数据放到别处的运营或开发人员：Airtable 表格、数据仓库、看板、内部工具。或者反过来：从负责寄送赠品的系统里添加达人，这样就没人需要重复录入。

它基于你自己的达人名单，也就是你寄过产品的达人。它不是用来搜索的达人数据库。如果你对达人 API 的需求是这个，Pozto 并不适合。

密钥、基础 URL 和限制

• 基础 URL： https://pozto.co/api/v1
• 密钥： 由团队所有者在 Brand 套餐的 设置 → API 中创建。密钥以 pz_ 开头，只显示一次：Pozto 只保存其指纹，所以请当场复制。按用途给每个密钥命名，可随时撤销。设置页会显示每个密钥最近一次的使用时间。
• 发送方式： 每个请求都带上 Authorization: Bearer pz_…。
• 范围： 一个密钥可读取并添加到你团队的所有品牌。
• 速率限制： 每个密钥每分钟 120 次请求。
• 分页： GET /creators 和 GET /posts 每次返回 100 条，加上 &limit= 最多 500 条。如果还有更多，响应会带有 next_cursor：将它作为 &cursor= 传回即可获取下一页。最后一页时它为 null。
• 格式： 输入和输出都是 JSON。id 为字符串，日期为 ISO 8601。

端点

达人和帖子包含哪些内容

达人数据包含姓名、邮箱、账号（以及每个账号是否已找到）、折扣码、状态，以及每份寄样：产品和包裹里的其他物品、所属活动、寄出和送达日期、以天计的截止期限、物流单号、费用、要求的帖子数和目前已发布的帖子数。

一条帖子就是一条视频，包含它发布到的每个平台：链接、文案、发布日期以及是否标记了你。然后是它计入的寄样和产品，以及 Pozto 如何判定的。接着是视频检查：是否找到了你的产品、每次出现在画面中的秒数、每次口播提到的原话，以及一段简短总结。还有广告声明：clear、weak 或 none，并附原因。

添加达人和帖子

POST /creators 接收 brand_id 和 handles：@用户名、主页链接或 Linktree 类链接，最多六个。还可接收 platform、name、email、codes、product（id 或名称；新名称会添加该产品）、shipped_at、delivered_at、due_days（不填则为 21）和 tracking。如果达人已在名单上（按任一账号或邮箱匹配），则为其添加寄样，而不会重复创建。新达人返回 201，已有达人返回 200，并附带达人 id 和寄样 id。

POST /posts 接收 brand_id 和 url，可选 creator_id 和 product_id。帖子会归到账号所属的达人名下，新达人会被加入你的名单，帖子随后进入视频检查队列。返回内容包括是否为新帖子、账号、平台，以及它是否算作关于你的帖子。

# 某个品牌下逾期的达人
curl "https://pozto.co/api/v1/creators?brand_id=BRAND_ID&status=late" \
  -H "Authorization: Bearer pz_…"

# 添加一位达人和你寄给他的赠品
curl -X POST https://pozto.co/api/v1/creators \
  -H "Authorization: Bearer pz_…" \
  -H "Content-Type: application/json" \
  -d '{"brand_id":"BRAND_ID","handles":["@maya.glows"],"product":"Glow Serum","shipped_at":"2026-10-14"}'

# 10 月 1 日以来的帖子，最新的在前
curl "https://pozto.co/api/v1/posts?brand_id=BRAND_ID&since=2026-10-01" \
  -H "Authorization: Bearer pz_…"

# 下一页：上一次响应中的 next_cursor
curl "https://pozto.co/api/v1/posts?brand_id=BRAND_ID&since=2026-10-01&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer pz_…"

错误

错误以 JSON 返回，附一句简单说明，例如 {"error": "…"}，状态码为 4xx：

• 400： 请求体不是 JSON，或某个字段无效，比如送达日期在未来。
• 401： 没有密钥，或密钥错误、已撤销。
• 403： 你的团队不在 Brand 套餐上。
• 404： 你的团队中没有该 brand_id 对应的品牌。
• 409： 品牌已锁定，因为你的套餐包含的品牌数少于团队正在使用的数量。
• 429： 一分钟内超过 120 次请求。

API 不做什么

• 没有达人搜索。 它只读取和添加你自己的名单。搜索达人请使用应用中的“找达人”。
• 响应中没有播放量、点赞或 EMV。 这些数据在应用中从 Starter 开始提供，也在每周报告中。详见达人营销报告。
• 没有 webhook。 要获取新帖子，请带 since 调用 GET /posts。
• 不能编辑或删除。 API 只读取和添加，修改和删除在应用中进行。
• 没有个人密钥。 密钥属于团队，且只有所有者能创建。

帖子里的内容和应用中一致：Pozto 通过查看视频的画面、音频和文案来找到帖子，所以未标记的帖子也会出现。达人追踪解释了帖子是如何被找到的。

价格

API 随 Brand 套餐提供：每月 $999，按年付费为每月 $799，包含 10 个品牌、1,000 位活跃达人、不限席位和单点登录。Pozto 的其他功能在更低的套餐中就已提供，免费套餐涵盖你的前 10 位达人。查看套餐。