DokumentasiDeveloper

API TaskerData

Pasang kampanye, kumpulkan kiriman pekerja, dan tinjau semuanya dari kode Anda sendiri, atau hubungkan tes kualifikasi eksternal. Setiap permintaan diautentikasi dengan kunci API Anda.

Ikhtisar

API Kampanye memungkinkan kode Anda melakukan hal yang sama seperti di dasbor pemberi tugas: membuat kampanye, memantau perkembangannya, mengunduh kiriman beserta buktinya, lalu menyetujui atau menolaknya. Endpoint kualifikasi eksternal memungkinkan tes di situs web Anda sendiri memberi tahu TaskerData apakah setiap pekerja lulus.

Semua permintaan dikirim ke https://taskerdata.com melalui HTTPS. Data dikirim dan diterima dalam format JSON.

Kampanye yang dibuat lewat API berbiaya sama dan mengikuti aturan yang sama seperti di dasbor. TaskerData meninjaunya sebelum tayang (pemberi tugas tepercaya langsung tayang), dan dana dicadangkan serta dibayarkan dengan cara yang sama.

Autentikasi

Buka dasbor pemberi tugas dan masuk ke menu API. Di sana ada dua kunci:

Kunci API: untuk permintaan sungguhan. API Kampanye membacanya dari header Authorization. Endpoint kualifikasi menerimanya sebagai api_token.
Kunci API Uji: hanya untuk endpoint uji tes kualifikasi, sehingga Anda bisa mencoba integrasi itu tanpa memengaruhi pekerja sungguhan.

Membuat kunci baru langsung menggantikan kunci lama, jadi perbarui backend Anda setiap kali melakukannya. Anda bisa membuat hingga 3 kunci baru per jam.

Penting: Rahasiakan kunci API Anda. Gunakan hanya di server Anda, jangan pernah di halaman web atau aplikasi yang bisa dibuka pengunjung.

Kirim kunci API Anda di setiap permintaan API Kampanye:

Authorization: Bearer YOUR_API_KEY

Anda bisa mengirim hingga 120 permintaan API Kampanye per menit. Header X-RateLimit-Remaining menunjukkan sisa permintaan. Setelah batas itu, Anda mendapat status 429, dan header Retry-After menunjukkan berapa detik Anda perlu menunggu.

API Kampanye

Buat kampanye dan tangani hasil kerja yang masuk, langsung dari kode Anda sendiri.

Daftar kampanye

GET/api/v1/campaigns

Kampanye Anda, yang terbaru lebih dulu. total adalah jumlah kampanye yang cocok, sehingga Anda bisa menelusurinya per halaman dengan limit dan offset.

Parameter query

Parameter	Deskripsi
`status`	Hanya kampanye dengan status ini: pending, in review, active, paused, completed, terminated, atau rejected
`limit`	Jumlah yang ditampilkan, 1 hingga 100 (default 20)
`offset`	Jumlah yang dilewati, untuk paging (default 0)

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

Respons · 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
}

Contoh error

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

Ambil satu kampanye

GET/api/v1/campaigns/{id}

Satu kampanye beserta pengaturannya dan jumlah kiriman yang menunggu peninjauan, menunggu revisi, disetujui, dan ditolak. Gunakan untuk memantau perkembangan kampanye.

Di alamat

Parameter	Deskripsi
`id` wajib	ID kampanye (id di daftar kampanye)

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

Respons · 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
    }
  }
}

Contoh error

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

Buat kampanye

POST/api/v1/campaigns

Memasang kampanye baru dan mencadangkan seluruh biayanya dari saldo tersedia Anda, persis seperti di dasbor. Respons berisi id kampanye, biayanya, dan statusnya: pending selama TaskerData meninjaunya, atau langsung active jika Anda pemberi tugas tepercaya.

Body JSON

Parameter	Deskripsi
`title` wajib	Judul kampanye, maksimal 100 karakter
`category` wajib	Kategori dari GET /api/v1/options. Kosongkan jika Anda memakai template
`instructions` wajib	Apa yang harus dilakukan pekerja, maksimal 5.000 karakter
`url`	Tautan yang dibuka pekerja. Wajib untuk kategori yang needs_url-nya true
`payment` wajib	Pembayaran per tugas dalam USD, minimal 0.12
`positions` wajib	Jumlah pekerja, minimal 10. Jika memakai file data template, jumlahnya dihitung dari baris file
`time_to_complete` wajib	Waktu dalam menit yang dimiliki pekerja untuk menyelesaikan tugas, 1 hingga 120
`time_to_rate` wajib	Waktu dalam hari yang Anda miliki untuk meninjau setiap kiriman, 1 hingga 30. Setelah itu kiriman disetujui otomatis
`proof.text`	Minta jawaban teks: beri tahu pekerja apa yang harus ditulis
`proof.images`	Minta tangkapan layar atau foto: satu deskripsi per gambar
`proof.video`	Minta video atau rekaman: apa yang harus ditampilkan
`targeting.region`	international (default), usa, west-europe, east-europe, latin-america, atau asia-africa
`targeting.exclude_countries`	Nama negara yang dikecualikan dari wilayah
`targeting.min_success_rate`	Tingkat keberhasilan minimum pekerja: 75 (default), 80, 85, 90, 95, atau 100
`targeting.type, targeting.group_id`	Atur type ke "group" dan group_id ke salah satu grup pekerja Anda agar tugas hanya dikirim ke grup itu
`qualification_id`	Hanya pekerja yang lulus tes kualifikasi ini yang bisa mengambil tugas
`template`	Gunakan salah satu template Anda sebagai pengganti instruksi: id, plus data berisi columns dan rows yang mengisi placeholder-nya, satu baris per tugas. answers_per_row (1 hingga 5) dan rows_per_task (1 hingga 50) bersifat opsional
`drip_feed`	Rilis pekerja secara bertahap: min_workers dan max_workers (1 hingga 50) serta interval_minutes (15, 30, 60, 120, 180, 360, 720, atau 1440)
`location`	Untuk Tugas lapangan lokal dan Mystery shopping: lat, lng, radius_m (50 hingga 50.000), dan address opsional

Untuk saat ini, kategori yang memerlukan file unggahan Anda (seperti Transkripsi audio atau Penandaan gambar), tugas video, dan contoh gambar hanya bisa dibuat di dasbor. Panduan Biaya menjelaskan cara harga dihitung.

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
    }
  }'

Respons · 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
  }
}

Contoh error

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

Ambil kiriman

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

Hasil kerja yang dikirim pekerja untuk satu kampanye, yang terlama lebih dulu, beserta buktinya: jawaban teks, tautan ke gambar dan video, jawaban template (answers), baris data yang mereka kerjakan, dan untuk tugas lapangan, lokasi mereka.

Di alamat

Parameter	Deskripsi
`id` wajib	ID kampanye (id di daftar kampanye)

Parameter query

Parameter	Deskripsi
`status`	to_review (pending dan resubmitted), pending, resubmitted, revision_requested, approved, atau rejected
`since`	Hanya kiriman yang dikirim pada atau setelah waktu ini, misalnya 2026-10-01T00:00:00Z
`after_id`	Untuk paging: hanya kiriman dengan id yang lebih besar. Gunakan next_after_id dari halaman sebelumnya
`limit`	Jumlah yang ditampilkan, 1 hingga 100 (default 50)

Untuk mengambil hasil kerja baru secara rutin, simpan id terakhir yang Anda terima dan kirim sebagai after_id di permintaan berikutnya. raw berisi semua yang dikirim pekerja, jika Anda membutuhkan sesuatu yang tidak tercantum.

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

Respons · 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
}

Contoh error

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

Tinjau kiriman

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

Setujui, tolak, atau minta revisi, sama seperti tombol di dasbor. Menyetujui berarti membayar pekerja dari dana yang dicadangkan. Menolak mengembalikan bayaran beserta biayanya ke saldo Anda dan membuka posisi itu untuk pekerja lain.

Di alamat

Parameter	Deskripsi
`id` wajib	ID kiriman

Body JSON

Parameter	Deskripsi
`action` wajib	approve, reject, atau revision
`reason`	Dengan reject: alasan yang dilihat pekerja
`note`	Dengan revision (wajib): apa yang harus diperbaiki pekerja

Anda hanya bisa meninjau kiriman selama kiriman itu menunggu peninjauan (pending atau resubmitted). Jumlah revisi dibatasi oleh batas revisi kampanye; setelah itu Anda hanya bisa menyetujui atau menolak.

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."
  }'

Respons · 200

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

Contoh error

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

Cek saldo Anda

GET/api/v1/balance

available adalah dana yang bisa Anda gunakan untuk kampanye baru, reserved adalah dana yang dicadangkan untuk kampanye yang sedang tayang, dan spent adalah jumlah yang sudah Anda bayarkan kepada pekerja sejauh ini.

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

Respons · 200

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

Opsi dan ID

GET/api/v1/options

Menampilkan kategori yang bisa Anda gunakan lewat API (needs_url dan needs_location menunjukkan mana yang memerlukan tautan atau lokasi), nilai penargetan dan drip feed yang diizinkan, serta ID template, grup pekerja, dan tes kualifikasi Anda.

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

Respons · 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"
    }
  ]
}

Error

API Kampanye menggunakan kode status HTTP. Jika terjadi masalah, success bernilai false dan error berisi code untuk diperiksa di kode Anda serta message untuk ditampilkan atau dicatat. Pemeriksaan kampanye memakai pesan yang sama seperti di dasbor.

Status	error.code	Artinya
400	`invalid_body, invalid_campaign, invalid_region, category_needs_files, invalid_status, invalid_since, invalid_action, note_required`	Ada yang kurang atau tidak diizinkan dalam permintaan. message menjelaskan apa itu.
401	`missing_api_key, invalid_api_key`	Tidak ada kunci API, atau kuncinya salah atau sudah diganti dengan yang lebih baru.
402	`insufficient_balance`	Saldo tersedia Anda tidak mencukupi untuk kampanye ini. Tambahkan dana lalu coba lagi.
403	`test_key_not_allowed, account_suspended`	Gunakan kunci API sungguhan Anda. Akun yang ditangguhkan tidak bisa menggunakan API.
404	`not_found`	Tidak ada kampanye atau kiriman dengan ID tersebut di akun Anda.
409	`already_reviewed, review_refused`	Kiriman sudah ditinjau, atau peninjauan tidak bisa dilakukan saat ini, misalnya karena batas revisi sudah tercapai.
429	`rate_limited`	Lebih dari 120 permintaan dalam satu menit. Tunggu selama jumlah detik di Retry-After.
500	`internal_error`	Ada masalah di pihak kami. Coba lagi, dan hubungi dukungan jika masalah terus terjadi.

Tes kualifikasi eksternal

Untuk tes kualifikasi yang berjalan di situs web Anda sendiri.

Laporkan hasil tes Aktif

GET/api/worker/external_qualification/data

Untuk tes kualifikasi yang ditandai sebagai eksternal. Pekerja membuka tes Anda dari halaman kualifikasi dan memasukkan token pekerja mereka di situs web Anda. Setelah mereka selesai, panggil endpoint ini dengan approve atau reject.

Parameter	Deskripsi
`qualification_id` wajib	ID tes kualifikasi Anda
`worker_token` wajib	Token pekerja yang dimasukkan pekerja di situs web Anda
`api_token` wajib	Kunci API Anda (kunci uji untuk endpoint uji)
`decision` wajib	approve atau reject

Jika tes memberikan bonus untuk kelulusan dan saldo pemberi tugas Anda tidak mencukupi, kiriman disimpan dengan status menunggu, sehingga Anda bisa mengisi saldo lalu menyetujuinya di dasbor.

Seorang pekerja hanya bisa dinilai sekali per tes. Tes harus aktif dan ditandai sebagai eksternal, dan kunci API harus milik pemilik tes.

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"

Respons · 200

{
  "success": true
}

Contoh error

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

Uji pengaturan Anda

POST/api/worker/external_qualification/data_test

Kirim kolom yang sama dalam format JSON ke endpoint uji, dengan kunci API uji Anda. Tidak ada yang disimpan dan tidak ada pekerja yang terpengaruh: endpoint ini hanya memeriksa permintaan Anda.

Parameter	Deskripsi
`qualification_id` wajib	ID tes kualifikasi Anda
`worker_token` wajib	Token pekerja yang dimasukkan pekerja di situs web Anda
`api_token` wajib	Kunci API Anda (kunci uji untuk endpoint uji)
`decision` wajib	approve atau reject

Kunci uji yang salah menghasilkan status 401; kolom yang kurang atau nilai decision yang salah menghasilkan status 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"
  }'

Respons · 200

{
  "success": true
}

Contoh error

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

Error hasil tes

Endpoint hasil selalu menjawab dengan status 200. Periksa success: jika nilainya false, error menjelaskan alasannya:

error	Artinya
`Missing required parameters: qualification_id, worker_token, api_token, decision`	Salah satu dari empat parameter tidak ada.
`Decision must be 'approve' or 'reject'`	decision berisi nilai lain.
`Invalid API token`	Kunci API salah atau sudah diganti dengan yang lebih baru.
`Worker token not found for this qualification`	Token bukan milik tes ini. Minta pekerja untuk memeriksanya.
`API token does not belong to the qualification owner`	Gunakan kunci dari akun yang membuat tes.
`This qualification is not configured for external submissions`	Tes tidak ditandai sebagai eksternal.
`This qualification is no longer active`	Tes sedang dijeda atau sudah selesai.
`This worker has already been evaluated for this qualification`	Setiap pekerja hanya mendapat satu hasil per tes.
`Worker account is suspended`	Pekerja tidak bisa mengikuti tes saat ini.
`No remaining positions for this qualification`	Semua tempat dalam tes sudah terisi.