DocumentațieDezvoltatori

API TaskerData

Plasează campanii, colectează trimiterile lucrătorilor și verifică-le din propriul cod sau conectează un test de calificare extern. Fiecare cerere este autentificată cu cheia ta API.

Prezentare generală

API-ul pentru campanii îi permite codului tău să facă ce faci tu în panoul de solicitant: să creeze campanii, să le urmărească progresul, să descarce trimiterile cu dovezile lor și să le aprobe sau respingă. Endpointurile pentru calificări externe permit unui test de pe propriul site să-i spună TaskerData dacă fiecare lucrător a promovat.

Toate cererile merg la https://taskerdata.com prin HTTPS. Trimite și primește JSON.

Campaniile create prin API costă la fel și respectă aceleași reguli ca în panou. TaskerData le verifică înainte de publicare (solicitanții de încredere sunt publicați imediat), iar banii sunt rezervați și plătiți în același mod.

Autentificare

Deschide panoul de solicitant și mergi la API. Acolo găsești două chei:

Cheie API: pentru cereri reale. API-ul pentru campanii o citește din antetul Authorization. Endpointul pentru calificări o primește ca api_token.
Cheie API de test: doar pentru endpointul de test al calificărilor, ca să poți încerca integrarea fără să afectezi lucrători reali.

Generarea unei chei noi o înlocuiește imediat pe cea veche, așa că actualizează-ți backendul când faci asta. Poți genera până la 3 chei noi pe oră.

Important: Păstrează secretă cheia API. Folosește-o doar pe serverul tău, niciodată într-o pagină web sau aplicație pe care vizitatorii o pot deschide.

Trimite cheia API cu fiecare cerere către API-ul pentru campanii:

Authorization: Bearer YOUR_API_KEY

Poți face până la 120 de cereri către API-ul pentru campanii pe minut. Antetul X-RateLimit-Remaining arată câte au mai rămas. După aceea primești starea 429, iar antetul Retry-After spune câte secunde trebuie să aștepți.

API-ul pentru campanii

Creează campanii și gestionează munca pe care o aduc, din propriul cod.

Listează campaniile

GET/api/v1/campaigns

Campaniile tale, cele mai noi primele. total arată câte campanii se potrivesc, ca să le poți parcurge cu limit și offset.

Parametri de interogare

Parametru	Descriere
`status`	Doar campaniile cu această stare: pending, in review, active, paused, completed, terminated sau rejected
`limit`	Câte să returneze, între 1 și 100 (implicit 20)
`offset`	Câte să sară, pentru paginare (implicit 0)

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

Răspuns · 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
}

Exemplu de eroare

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

Obține o campanie

GET/api/v1/campaigns/{id}

O campanie cu setările ei și câte trimiteri așteaptă verificarea, așteaptă o revizuire, sunt aprobate și respinse. Folosește-o pentru a urmări progresul unei campanii.

În adresă

Parametru	Descriere
`id` obligatoriu	ID-ul campaniei (id în lista de campanii)

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

Răspuns · 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
    }
  }
}

Exemplu de eroare

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

Creează o campanie

POST/api/v1/campaigns

Plasează o campanie nouă și rezervă costul ei total din soldul disponibil, exact ca în panou. Răspunsul include id-ul campaniei, costul și starea: pending cât TaskerData o verifică sau active imediat dacă ești solicitant de încredere.

Corp JSON

Parametru	Descriere
`title` obligatoriu	Titlul campaniei, până la 100 de caractere
`category` obligatoriu	O categorie din GET /api/v1/options. Omite-o când folosești un șablon
`instructions` obligatoriu	Ce trebuie să facă lucrătorii, până la 5.000 de caractere
`url`	Linkul pe care îl deschid lucrătorii. Obligatoriu pentru categoriile la care needs_url este true
`payment` obligatoriu	Plata per sarcină în USD, cel puțin 0.12
`positions` obligatoriu	Câți lucrători, cel puțin 10. Cu un fișier de date pentru șablon, se calculează din rânduri
`time_to_complete` obligatoriu	Minutele pe care le are un lucrător pentru a termina, între 1 și 120
`time_to_rate` obligatoriu	Zilele pe care le ai pentru a verifica fiecare trimitere, între 1 și 30. După aceea este aprobată automat
`proof.text`	Cere un răspuns text: spune-i lucrătorului ce să scrie
`proof.images`	Cere capturi de ecran sau fotografii: o descriere per imagine
`proof.video`	Cere un videoclip sau o înregistrare: ce trebuie să arate
`targeting.region`	international (implicit), usa, west-europe, east-europe, latin-america sau asia-africa
`targeting.exclude_countries`	Numele țărilor de exclus din regiune
`targeting.min_success_rate`	Rata minimă de succes a lucrătorului: 75 (implicit), 80, 85, 90, 95 sau 100
`targeting.type, targeting.group_id`	Setează type la "group" și group_id la unul dintre grupurile tale de lucrători pentru a trimite sarcina doar acelui grup
`qualification_id`	Doar lucrătorii care au promovat acest test de calificare pot lua sarcina
`template`	Folosește unul dintre șabloanele tale în loc de instrucțiuni: id, plus data cu columns și rows care îi completează substituenții, un rând per sarcină. answers_per_row (1 până la 5) și rows_per_task (1 până la 50) sunt opționale
`drip_feed`	Eliberează lucrătorii în loturi: min_workers și max_workers (1 până la 50) și interval_minutes (15, 30, 60, 120, 180, 360, 720 sau 1440)
`location`	Pentru Sarcini locale pe teren și Mystery shopping: lat, lng, radius_m (50 până la 50.000) și o adresă opțională

Deocamdată, categoriile care au nevoie de fișiere încărcate de tine (precum Transcriere audio sau Etichetare de imagini), sarcinile video și imaginile exemplu pot fi create doar în panou. Ghidul Costuri și taxe explică modul de calcul al prețului.

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

Răspuns · 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
  }
}

Exemplu de eroare

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

Obține trimiterile

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

Munca trimisă de lucrători pentru o campanie, cele mai vechi primele, cu dovezile lor: răspunsul text, linkuri către imagini și video, răspunsurile la șablon (answers), rândul de date la care au lucrat și, pentru sarcinile pe teren, locația lor.

În adresă

Parametru	Descriere
`id` obligatoriu	ID-ul campaniei (id în lista de campanii)

Parametri de interogare

Parametru	Descriere
`status`	to_review (pending și resubmitted), pending, resubmitted, revision_requested, approved sau rejected
`since`	Doar trimiterile trimise la sau după acest moment, de exemplu 2026-10-01T00:00:00Z
`after_id`	Pentru paginare: doar trimiterile cu un id mai mare. Folosește next_after_id din pagina anterioară
`limit`	Câte să returneze, între 1 și 100 (implicit 50)

Pentru a colecta regulat munca nouă, păstrează ultimul id primit și trimite-l ca after_id data viitoare. raw conține tot ce a trimis lucrătorul, în caz că ai nevoie de ceva ce nu este listat.

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

Răspuns · 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
}

Exemplu de eroare

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

Verifică o trimitere

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

Aprobă, respinge sau cere o revizuire, la fel ca butoanele din panou. Aprobarea îl plătește pe lucrător din banii rezervați. Respingerea returnează plata și comisionul ei în soldul tău și eliberează locul pentru alt lucrător.

În adresă

Parametru	Descriere
`id` obligatoriu	ID-ul trimiterii

Corp JSON

Parametru	Descriere
`action` obligatoriu	approve, reject sau revision
`reason`	Cu reject: motivul pe care îl vede lucrătorul
`note`	Cu revision (obligatoriu): ce trebuie să corecteze lucrătorul

Poți verifica o trimitere doar cât timp așteaptă verificarea (pending sau resubmitted). Revizuirile sunt limitate de limita de revizuiri a campaniei; după aceea poți doar să aprobi sau să respingi.

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

Răspuns · 200

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

Exemplu de eroare

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

Verifică-ți soldul

GET/api/v1/balance

available este ce poți cheltui pe campanii noi, reserved este suma păstrată pentru campaniile active, iar spent este cât ai plătit lucrătorilor până acum.

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

Răspuns · 200

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

Opțiuni și ID-uri

GET/api/v1/options

Listează categoriile pe care le poți folosi prin API (needs_url și needs_location arată care au nevoie de un link sau de o locație), valorile permise pentru targetare și distribuire treptată și ID-urile șabloanelor, grupurilor de lucrători și testelor tale de calificare.

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

Răspuns · 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"
    }
  ]
}

Erori

API-ul pentru campanii folosește coduri de stare HTTP. Când ceva nu merge, success este false, iar error are un code de verificat în codul tău și un message de afișat sau înregistrat. Verificările campaniilor folosesc aceleași mesaje ca panoul.

Stare	error.code	Ce înseamnă
400	`invalid_body, invalid_campaign, invalid_region, category_needs_files, invalid_status, invalid_since, invalid_action, note_required`	Ceva din cerere lipsește sau nu este permis. message spune ce.
401	`missing_api_key, invalid_api_key`	Nu există cheie API sau cheia este greșită ori a fost înlocuită de una mai nouă.
402	`insufficient_balance`	Soldul disponibil nu acoperă campania. Adaugă fonduri și încearcă din nou.
403	`test_key_not_allowed, account_suspended`	Folosește cheia API reală. Un cont suspendat nu poate folosi API-ul.
404	`not_found`	Nu există nicio campanie sau trimitere cu acest ID în contul tău.
409	`already_reviewed, review_refused`	Trimiterea a fost deja verificată sau verificarea nu este posibilă acum, de exemplu pentru că s-a atins limita de revizuiri.
429	`rate_limited`	Mai mult de 120 de cereri într-un minut. Așteaptă numărul de secunde din Retry-After.
500	`internal_error`	O problemă de partea noastră. Încearcă din nou și contactează asistența dacă se repetă.

Teste de calificare externe

Pentru testele de calificare care rulează pe propriul site.

Raportează un rezultat de test Live

GET/api/worker/external_qualification/data

Pentru testele de calificare marcate ca externe. Lucrătorul îți deschide testul din calificare și introduce tokenul de lucrător pe site-ul tău. Când termină, apelează acest endpoint cu approve sau reject.

Parametru	Descriere
`qualification_id` obligatoriu	ID-ul testului tău de calificare
`worker_token` obligatoriu	Tokenul de lucrător introdus de lucrător pe site-ul tău
`api_token` obligatoriu	Cheia ta API (cheia de test pentru endpointul de test)
`decision` obligatoriu	approve sau reject

Dacă testul plătește un bonus la promovare și soldul de solicitant nu îl acoperă, trimiterea este salvată ca în așteptare, ca să poți alimenta soldul și să o aprobi din panou.

Un lucrător poate fi evaluat o singură dată per test. Testul trebuie să fie activ și marcat ca extern, iar cheia API trebuie să aparțină proprietarului testului.

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"

Răspuns · 200

{
  "success": true
}

Exemplu de eroare

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

Testează-ți configurarea

POST/api/worker/external_qualification/data_test

Trimite aceleași câmpuri ca JSON la endpointul de test, cu cheia API de test. Nu se salvează nimic și niciun lucrător nu este afectat: doar îți verifică cererea.

Parametru	Descriere
`qualification_id` obligatoriu	ID-ul testului tău de calificare
`worker_token` obligatoriu	Tokenul de lucrător introdus de lucrător pe site-ul tău
`api_token` obligatoriu	Cheia ta API (cheia de test pentru endpointul de test)
`decision` obligatoriu	approve sau reject

O cheie de test greșită returnează starea 401; câmpurile lipsă sau o decizie greșită returnează starea 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"
  }'

Răspuns · 200

{
  "success": true
}

Exemplu de eroare

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

Erori la rezultatele testelor

Endpointul pentru rezultate răspunde întotdeauna cu starea 200. Verifică success: când este false, error spune de ce:

error	Ce înseamnă
`Missing required parameters: qualification_id, worker_token, api_token, decision`	Lipsește unul dintre cei patru parametri.
`Decision must be 'approve' or 'reject'`	decision are altă valoare.
`Invalid API token`	Cheia API este greșită sau a fost înlocuită de una mai nouă.
`Worker token not found for this qualification`	Tokenul nu aparține acestui test. Roagă lucrătorul să-l verifice.
`API token does not belong to the qualification owner`	Folosește cheia contului care a creat testul.
`This qualification is not configured for external submissions`	Testul nu este marcat ca extern.
`This qualification is no longer active`	Testul este pe pauză sau s-a încheiat.
`This worker has already been evaluated for this qualification`	Fiecare lucrător primește un singur rezultat per test.
`Worker account is suspended`	Lucrătorul nu poate susține teste momentan.
`No remaining positions for this qualification`	Toate locurile din test sunt ocupate.