文档开发者

TaskerData API

用你自己的代码发布活动、收集并审核工作者的提交，或连接外部资格测试。每个请求都使用你的 API 密钥进行身份验证。

概览

活动 API 让你的代码完成你在发布者控制台中做的事：创建活动、跟踪进度、下载提交及其凭证，并通过或拒绝它们。外部资格测试端点让你网站上的测试告诉 TaskerData 每位工作者是否通过。

所有请求都通过 HTTPS 发送到 https://taskerdata.com，请求和响应均为 JSON 格式。

通过 API 创建的活动与在控制台中创建的费用相同、规则相同。上线前由 TaskerData 审核（受信任的发布者会立即上线），资金的预留和支付方式也一样。

身份验证

打开发布者控制台，进入 API。你会看到两个密钥：

API 密钥：用于真实请求。活动 API 从 Authorization 请求头中读取它，资格测试端点则以 api_token 接收它。
测试 API 密钥：仅用于资格测试的测试端点，让你在不影响真实工作者的情况下试用该集成。

生成新密钥会立即替换旧密钥，所以生成后请同步更新你的后端。每小时最多可生成 3 个新密钥。

重要： 请妥善保管你的 API 密钥，只在服务器上使用，绝不要放在访客能打开的网页或应用中。

每个活动 API 请求都要带上你的 API 密钥：

Authorization: Bearer YOUR_API_KEY

每分钟最多可发送 120 个活动 API 请求。X-RateLimit-Remaining 请求头显示还剩多少次。超出后会返回状态码 429，Retry-After 请求头会告诉你需要等待几秒。

活动 API

用你自己的代码创建活动，并处理活动收到的工作。

列出活动

GET/api/v1/campaigns

你的活动，按从新到旧排列。total 是符合条件的活动总数，你可以用 limit 和 offset 分页浏览。

查询参数

参数	说明
`status`	只返回该状态的活动：pending、in review、active、paused、completed、terminated 或 rejected
`limit`	返回数量，1 到 100（默认 20）
`offset`	跳过的数量，用于分页（默认 0）

curl "https://taskerdata.com/api/v1/campaigns?status=active&limit=20" \
  -H "Authorization: Bearer $TASKERDATA_API_KEY"

响应 · 200

{
  "success": true,
  "campaigns": [
    {
      "id": "Ab12…-Cd34…-Ef56…",
      "title": "Test our sign-up page",
      "status": "active",
      "category": "Website Testing",
      "type": "instructions",
      "url": "https://example.com/signup",
      "payment": 0.5,
      "positions": 50,
      "filled_positions": 12,
      "time_to_complete": 10,
      "time_to_rate": 3,
      "cost": 34.06,
      "proof": {
        "text": "What went wrong?",
        "images": [
          "Screenshot after signing up"
        ],
        "video": null
      },
      "qualification_id": null,
      "created_at": "2026-10-16T09:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

错误示例

// status 401
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key."
  }
}

获取单个活动

GET/api/v1/campaigns/{id}

返回一个活动的设置，以及待审核、等待修改、已通过和已拒绝的提交数量。可用来跟踪活动进度。

路径参数

参数	说明
`id` 必填	活动 ID（活动列表中的 id）

curl "https://taskerdata.com/api/v1/campaigns/CAMPAIGN_ID" \
  -H "Authorization: Bearer $TASKERDATA_API_KEY"

响应 · 200

{
  "success": true,
  "campaign": {
    "id": "Ab12…-Cd34…-Ef56…",
    "title": "Test our sign-up page",
    "status": "active",
    "category": "Website Testing",
    "type": "instructions",
    "url": "https://example.com/signup",
    "payment": 0.5,
    "positions": 50,
    "filled_positions": 12,
    "time_to_complete": 10,
    "time_to_rate": 3,
    "cost": 34.06,
    "proof": {
      "text": "What went wrong?",
      "images": [
        "Screenshot after signing up"
      ],
      "video": null
    },
    "qualification_id": null,
    "created_at": "2026-10-16T09:30:00.000Z",
    "submissions": {
      "total": 14,
      "to_review": 3,
      "revision_requested": 1,
      "approved": 9,
      "rejected": 1
    }
  }
}

错误示例

// status 404
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Campaign not found."
  }
}

创建活动

POST/api/v1/campaigns

发布一个新活动，并从你的可用余额中预留全部费用，与控制台中完全相同。响应包含活动的 id、费用和状态：TaskerData 审核期间为 pending，如果你是受信任的发布者则直接为 active。

JSON 请求体

参数	说明
`title` 必填	活动标题，最多 100 个字符
`category` 必填	来自 GET /api/v1/options 的类别。使用模板时不要填写
`instructions` 必填	工作者需要做什么，最多 5,000 个字符
`url`	工作者打开的链接。needs_url 为 true 的类别必须填写
`payment` 必填	每个任务的报酬（美元），最低 0.12
`positions` 必填	工作者数量，最少 10。使用模板数据文件时根据行数自动计算
`time_to_complete` 必填	工作者完成任务的时限（分钟），1 到 120
`time_to_rate` 必填	你审核每个提交的期限（天），1 到 30。超过期限会自动通过
`proof.text`	要求文字回答：告诉工作者要写什么
`proof.images`	要求截图或照片：每张图片一条说明
`proof.video`	要求视频或录屏：说明应该显示什么
`targeting.region`	international（默认）、usa、west-europe、east-europe、latin-america 或 asia-africa
`targeting.exclude_countries`	要从该地区中排除的国家名称
`targeting.min_success_rate`	工作者最低通过率：75（默认）、80、85、90、95 或 100
`targeting.type, targeting.group_id`	将 type 设为 group，并将 group_id 设为你的某个工作者分组，任务就只发给该分组
`qualification_id`	只有通过此资格测试的工作者才能接这个任务
`template`	用你的某个模板代替说明：提供 id，以及包含 columns 和 rows 的 data 来填充模板占位符，每行一个任务。answers_per_row（1 到 5）和 rows_per_task（1 到 50）为选填
`drip_feed`	分批放出名额：min_workers 和 max_workers（1 到 50）以及 interval_minutes（15、30、60、120、180、360、720 或 1440）
`location`	适用于本地实地任务和神秘顾客：lat、lng、radius_m（50 到 50,000）以及选填的 address

目前，需要上传文件的类别（如音频转写或图片标签）、视频任务和示例图片只能在控制台中创建。费用与手续费指南介绍了价格的计算方式。

curl -X POST "https://taskerdata.com/api/v1/campaigns" \
  -H "Authorization: Bearer $TASKERDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test our sign-up page",
    "category": "Website Testing",
    "url": "https://example.com/signup",
    "instructions": "Open the page, create an account and tell us anything that went wrong.",
    "payment": 0.5,
    "positions": 50,
    "time_to_complete": 10,
    "time_to_rate": 3,
    "proof": {
      "text": "What went wrong?",
      "images": [
        "Screenshot after signing up"
      ]
    },
    "targeting": {
      "region": "international",
      "min_success_rate": 90
    }
  }'

响应 · 201

{
  "success": true,
  "campaign": {
    "id": "Ab12…-Cd34…-Ef56…",
    "title": "Test our sign-up page",
    "status": "pending",
    "category": "Website Testing",
    "type": "instructions",
    "url": "https://example.com/signup",
    "payment": 0.5,
    "positions": 50,
    "filled_positions": 0,
    "time_to_complete": 10,
    "time_to_rate": 3,
    "cost": 34.06,
    "proof": {
      "text": "What went wrong?",
      "images": [
        "Screenshot after signing up"
      ],
      "video": null
    },
    "qualification_id": null,
    "created_at": "2026-10-16T09:30:00.000Z"
  },
  "balance": {
    "available": 65.94,
    "reserved": 34.06
  }
}

错误示例

// status 402
{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance"
  }
}

获取提交

GET/api/v1/campaigns/{id}/submissions

某个活动中工作者发来的工作，按从旧到新排列，并附带凭证：文字回答、图片和视频链接、模板答案（answers）、他们处理的数据行，以及实地任务中的位置。

路径参数

参数	说明
`id` 必填	活动 ID（活动列表中的 id）

查询参数

参数	说明
`status`	to_review（pending 和 resubmitted）、pending、resubmitted、revision_requested、approved 或 rejected
`since`	只返回在此时间或之后发送的提交，例如 2026-10-01T00:00:00Z
`after_id`	用于分页：只返回 id 更大的提交。请使用上一页返回的 next_after_id
`limit`	返回数量，1 到 100（默认 50）

如需定期获取新工作，请记下收到的最后一个 id，下次作为 after_id 发送。raw 包含工作者发送的全部内容，以备你需要未列出的信息。

curl "https://taskerdata.com/api/v1/campaigns/CAMPAIGN_ID/submissions?status=to_review&after_id=0" \
  -H "Authorization: Bearer $TASKERDATA_API_KEY"

响应 · 200

{
  "success": true,
  "submissions": [
    {
      "id": 1842,
      "campaign_id": "Ab12…-Cd34…-Ef56…",
      "worker_id": "wK3…",
      "status": "pending",
      "started_at": "2026-10-16 10:02:11",
      "submitted_at": "2026-10-16 10:09:45",
      "revision_count": 0,
      "revision_note": null,
      "rejection_reason": null,
      "payment": 0.5,
      "proof": {
        "text": "The confirm button did nothing on mobile.",
        "image_urls": [
          "https://storage.taskerdata.com/…/proof_0.png"
        ],
        "video_url": null
      },
      "answers": null,
      "data_row": null,
      "data_row_number": null,
      "items": null,
      "location": null,
      "raw": {
        "textProof": "…"
      }
    }
  ],
  "has_more": false,
  "next_after_id": null
}

错误示例

// status 400
{
  "success": false,
  "error": {
    "code": "invalid_status",
    "message": "status must be one of: to_review, pending, resubmitted, revision_requested, approved, rejected."
  }
}

审核提交

POST/api/v1/submissions/{id}/review

通过、拒绝或要求修改，与控制台中的按钮效果相同。通过后会从预留资金中向工作者付款。拒绝会把报酬及其手续费退回你的余额，并空出名额给其他工作者。

路径参数

参数	说明
`id` 必填	提交 ID

JSON 请求体

参数	说明
`action` 必填	approve、reject 或 revision
`reason`	配合 reject：工作者看到的拒绝理由
`note`	配合 revision（必填）：工作者需要修改什么

只有在提交等待审核时（pending 或 resubmitted）才能审核。修改次数受活动的修改上限限制，达到上限后只能通过或拒绝。

curl -X POST "https://taskerdata.com/api/v1/submissions/1842/review" \
  -H "Authorization: Bearer $TASKERDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "revision",
    "note": "Please add a screenshot of the error message."
  }'

响应 · 200

{
  "success": true,
  "submission": {
    "id": 1842,
    "status": "revision_requested"
  },
  "balance": {
    "available": 65.94,
    "reserved": 34.06
  }
}

错误示例

// status 409
{
  "success": false,
  "error": {
    "code": "already_reviewed",
    "message": "Submission already reviewed"
  }
}

查看余额

GET/api/v1/balance

available 是你可用于新活动的金额，reserved 是为进行中的活动预留的金额，spent 是你到目前为止已支付给工作者的金额。

curl "https://taskerdata.com/api/v1/balance" \
  -H "Authorization: Bearer $TASKERDATA_API_KEY"

响应 · 200

{
  "success": true,
  "balance": {
    "available": 65.94,
    "reserved": 34.06,
    "spent": 212.4
  }
}

选项与 ID

GET/api/v1/options

列出可通过 API 使用的类别（needs_url 和 needs_location 表示哪些类别需要链接或位置）、允许的定向和逐步投放取值，以及你的模板、工作者分组和资格测试的 ID。

curl "https://taskerdata.com/api/v1/options" \
  -H "Authorization: Bearer $TASKERDATA_API_KEY"

响应 · 200

{
  "success": true,
  "categories": [
    {
      "name": "Website Testing",
      "needs_url": true,
      "needs_location": false
    },
    "…"
  ],
  "regions": [
    "international",
    "usa",
    "west-europe",
    "east-europe",
    "latin-america",
    "asia-africa"
  ],
  "min_success_rates": [
    75,
    80,
    85,
    90,
    95,
    100
  ],
  "drip_feed_intervals": [
    15,
    30,
    60,
    120,
    180,
    360,
    720,
    1440
  ],
  "templates": [
    {
      "id": 12,
      "title": "Sentiment check"
    }
  ],
  "worker_groups": [
    {
      "id": 3,
      "name": "Trusted testers",
      "workers": 25
    }
  ],
  "qualifications": [
    {
      "id": "Qa1…",
      "title": "English test",
      "status": "active"
    }
  ]
}

错误

活动 API 使用 HTTP 状态码。出错时 success 为 false，error 中包含一个供代码判断的 code，以及一条可显示或记录的 message。活动检查使用与控制台相同的提示信息。

状态码	error.code	含义
400	`invalid_body, invalid_campaign, invalid_region, category_needs_files, invalid_status, invalid_since, invalid_action, note_required`	请求中缺少某些内容或包含不允许的内容。message 会说明具体问题。
401	`missing_api_key, invalid_api_key`	没有 API 密钥，或密钥错误，或已被更新的密钥替换。
402	`insufficient_balance`	你的可用余额不足以支付该活动。请充值后重试。
403	`test_key_not_allowed, account_suspended`	请使用你的正式 API 密钥。被暂停的账户无法使用 API。
404	`not_found`	你的账户中没有该 ID 对应的活动或提交。
409	`already_reviewed, review_refused`	该提交已经审核过，或目前无法审核，例如已达到修改上限。
429	`rate_limited`	一分钟内请求超过 120 次。请等待 Retry-After 中给出的秒数。
500	`internal_error`	我们这边出了问题。请重试，如果问题持续出现，请联系客服。

外部资格测试

适用于在你自己网站上进行的资格测试。

上报测试结果已上线

GET/api/worker/external_qualification/data

适用于标记为外部来源的资格测试。工作者从资格测试中打开你的测试，并在你的网站上输入他们的工作者令牌。完成后，用 approve 或 reject 调用此端点。

参数	说明
`qualification_id` 必填	你的资格测试 ID
`worker_token` 必填	工作者在你的网站上输入的工作者令牌
`api_token` 必填	你的 API 密钥（测试端点使用测试密钥）
`decision` 必填	approve 或 reject

如果测试对通过者发放奖金，而你的发布者余额不足以支付，该提交会改为保存为待审核，你可以充值后在控制台中通过。

每位工作者在每个测试中只能被评估一次。测试必须处于活跃状态并标记为外部来源，且 API 密钥必须属于该测试的所有者。

curl -G "https://taskerdata.com/api/worker/external_qualification/data" \
  --data-urlencode "qualification_id=QUAL_ID" \
  --data-urlencode "worker_token=WORKER_TOKEN" \
  --data-urlencode "api_token=YOUR_API_KEY" \
  --data-urlencode "decision=approve"

响应 · 200

{
  "success": true
}

错误示例

{
  "success": false,
  "error": "This worker has already been evaluated for this qualification"
}

测试你的配置

POST/api/worker/external_qualification/data_test

用你的测试 API 密钥，以 JSON 格式向测试端点发送相同的字段。不会保存任何数据，也不会影响任何工作者，只会检查你的请求。

参数	说明
`qualification_id` 必填	你的资格测试 ID
`worker_token` 必填	工作者在你的网站上输入的工作者令牌
`api_token` 必填	你的 API 密钥（测试端点使用测试密钥）
`decision` 必填	approve 或 reject

测试密钥错误会返回状态码 401；缺少字段或 decision 值错误会返回状态码 400。

curl -X POST "https://taskerdata.com/api/worker/external_qualification/data_test" \
  -H "Content-Type: application/json" \
  -d '{
    "qualification_id": "QUAL_ID",
    "worker_token": "WORKER_TOKEN",
    "api_token": "YOUR_TEST_API_KEY",
    "decision": "approve"
  }'

响应 · 200

{
  "success": true
}

错误示例

// status 401
{
  "statusCode": 401,
  "statusMessage": "Invalid API test key"
}

测试结果错误

结果端点始终返回状态码 200。请检查 success：当它为 false 时，error 会说明原因：

error	含义
`Missing required parameters: qualification_id, worker_token, api_token, decision`	四个参数中缺少了一个。
`Decision must be 'approve' or 'reject'`	decision 的值不是这两者之一。
`Invalid API token`	API 密钥错误，或已被更新的密钥替换。
`Worker token not found for this qualification`	该令牌不属于这个测试。请让工作者检查一下。
`API token does not belong to the qualification owner`	请使用创建该测试的账户的密钥。
`This qualification is not configured for external submissions`	该测试未标记为外部来源。
`This qualification is no longer active`	该测试已暂停或已结束。
`This worker has already been evaluated for this qualification`	每位工作者在每个测试中只能有一个结果。
`Worker account is suspended`	该工作者目前无法参加测试。
`No remaining positions for this qualification`	测试的所有名额都已占满。

TaskerData API

概览

身份验证

列出活动

获取单个活动

创建活动

获取提交

审核提交

查看余额

选项与 ID

错误

上报测试结果 已上线

测试你的配置

测试结果错误

上报测试结果已上线