DocumentazioneSviluppatori

API di TaskerData

Pubblica campagne, raccogli gli invii dei lavoratori e valutali dal tuo codice, oppure collega un test di qualifica esterno. Ogni richiesta è autenticata con la tua chiave API.

Panoramica

La Campaign API permette al tuo codice di fare ciò che fai nella dashboard del committente: creare campagne, seguirne l'avanzamento, scaricare gli invii con le loro prove e approvarli o rifiutarli. Gli endpoint dei test di qualifica esterni permettono a un test sul tuo sito web di comunicare a TaskerData se ogni lavoratore lo ha superato.

Tutte le richieste vanno a https://taskerdata.com tramite HTTPS. Invia e ricevi JSON.

Le campagne create tramite l'API costano lo stesso e seguono le stesse regole di quelle create nella dashboard. TaskerData le controlla prima della pubblicazione (i committenti affidabili vengono pubblicati subito), e il denaro viene riservato e pagato allo stesso modo.

Autenticazione

Apri la dashboard del committente e vai su API. Lì troverai due chiavi:

Chiave API: per le richieste reali. La Campaign API la legge dall'intestazione Authorization. L'endpoint dei test di qualifica la riceve come api_token.
Chiave API di test: solo per l'endpoint di test dei test di qualifica, così puoi provare quell'integrazione senza coinvolgere lavoratori reali.

Generare una nuova chiave sostituisce subito quella vecchia, quindi aggiorna il tuo backend quando lo fai. Puoi generare fino a 3 nuove chiavi all'ora.

Importante: Mantieni segreta la tua chiave API. Usala solo sul tuo server, mai in una pagina web o in un'app che i visitatori possono aprire.

Invia la tua chiave API con ogni richiesta alla Campaign API:

Authorization: Bearer YOUR_API_KEY

Puoi fare fino a 120 richieste alla Campaign API al minuto. L'intestazione X-RateLimit-Remaining mostra quante ne restano. Dopo di che ricevi lo stato 429, e l'intestazione Retry-After indica quanti secondi aspettare.

Campaign API

Crea campagne e gestisci il lavoro che portano, dal tuo codice.

Elenca le campagne

GET/api/v1/campaigns

Le tue campagne, dalla più recente. total indica quante campagne corrispondono, così puoi scorrerle con limit e offset.

Parametri di query

Parametro	Descrizione
`status`	Solo le campagne con questo stato: pending, in review, active, paused, completed, terminated o rejected
`limit`	Quante restituirne, da 1 a 100 (predefinito 20)
`offset`	Quante saltarne, per la paginazione (predefinito 0)

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

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

Esempio di errore

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

Ottieni una campagna

GET/api/v1/campaigns/{id}

Una campagna con le sue impostazioni e quanti invii sono in attesa di valutazione, in attesa di revisione, approvati e rifiutati. Usalo per seguire l'avanzamento di una campagna.

Nell'indirizzo

Parametro	Descrizione
`id` obbligatorio	L'ID della campagna (id nell'elenco delle campagne)

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

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

Esempio di errore

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

Crea una campagna

POST/api/v1/campaigns

Pubblica una nuova campagna e riserva il suo costo completo dal tuo saldo disponibile, esattamente come la dashboard. La risposta include l'id della campagna, il suo costo e il suo stato: pending mentre TaskerData la controlla, oppure active subito se sei un committente affidabile.

Corpo JSON

Parametro	Descrizione
`title` obbligatorio	Titolo della campagna, fino a 100 caratteri
`category` obbligatorio	Una categoria da GET /api/v1/options. Omettila quando usi un modello
`instructions` obbligatorio	Cosa devono fare i lavoratori, fino a 5,000 caratteri
`url`	Il link che aprono i lavoratori. Obbligatorio per le categorie in cui needs_url è true
`payment` obbligatorio	Pagamento per attività in USD, almeno 0.12
`positions` obbligatorio	Quanti lavoratori, almeno 10. Con un file di dati per il modello viene calcolato dalle righe
`time_to_complete` obbligatorio	Minuti che un lavoratore ha per finire, da 1 a 120
`time_to_rate` obbligatorio	Giorni che hai per valutare ogni invio, da 1 a 30. Dopo di che viene approvato automaticamente
`proof.text`	Chiedi una risposta testuale: indica al lavoratore cosa scrivere
`proof.images`	Chiedi screenshot o foto: una descrizione per immagine
`proof.video`	Chiedi un video o una registrazione: cosa deve mostrare
`targeting.region`	international (predefinito), usa, west-europe, east-europe, latin-america o asia-africa
`targeting.exclude_countries`	Nomi dei paesi da escludere dalla regione
`targeting.min_success_rate`	Tasso di successo minimo del lavoratore: 75 (predefinito), 80, 85, 90, 95 o 100
`targeting.type, targeting.group_id`	Imposta type su "group" e group_id su uno dei tuoi gruppi di lavoratori per inviare l'attività solo a quel gruppo
`qualification_id`	Solo i lavoratori che hanno superato questo test di qualifica possono accettare l'attività
`template`	Usa uno dei tuoi modelli invece delle istruzioni: id, più data con columns e rows che ne compilano i segnaposto, una riga per attività. answers_per_row (da 1 a 5) e rows_per_task (da 1 a 50) sono facoltativi
`drip_feed`	Rilascia i lavoratori a gruppi: min_workers e max_workers (da 1 a 50) e interval_minutes (15, 30, 60, 120, 180, 360, 720 o 1440)
`location`	Per Attività sul campo e Mystery shopping: lat, lng, radius_m (da 50 a 50,000) e un address facoltativo

Per ora, le categorie che richiedono file da caricare (come Trascrizione audio o Etichettatura di immagini), le attività video e le immagini di esempio si possono creare solo nella dashboard. La guida Costi e commissioni spiega come viene calcolato il prezzo.

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

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

Esempio di errore

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

Ottieni gli invii

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

Il lavoro inviato dai lavoratori per una campagna, dal meno recente, con le loro prove: la risposta testuale, i link a immagini e video, le risposte al modello (answers), la riga di dati su cui hanno lavorato e, per le attività sul campo, la loro posizione.

Nell'indirizzo

Parametro	Descrizione
`id` obbligatorio	L'ID della campagna (id nell'elenco delle campagne)

Parametri di query

Parametro	Descrizione
`status`	to_review (pending e resubmitted), pending, resubmitted, revision_requested, approved o rejected
`since`	Solo gli invii inviati in questo momento o dopo, ad esempio 2026-10-01T00:00:00Z
`after_id`	Per la paginazione: solo gli invii con un id più alto. Usa next_after_id della pagina precedente
`limit`	Quanti restituirne, da 1 a 100 (predefinito 50)

Per raccogliere regolarmente il nuovo lavoro, conserva l'ultimo id ricevuto e invialo come after_id la volta successiva. raw contiene tutto ciò che ha inviato il lavoratore, nel caso ti serva qualcosa che non è elencato.

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

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

Esempio di errore

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

Valuta un invio

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

Approva, rifiuta o chiedi una revisione, come con i pulsanti della dashboard. L'approvazione paga il lavoratore con il denaro riservato. Il rifiuto restituisce il pagamento e la sua commissione al tuo saldo e libera il posto per un altro lavoratore.

Nell'indirizzo

Parametro	Descrizione
`id` obbligatorio	L'ID dell'invio

Corpo JSON

Parametro	Descrizione
`action` obbligatorio	approve, reject o revision
`reason`	Con reject: il motivo che vede il lavoratore
`note`	Con revision (obbligatorio): cosa deve correggere il lavoratore

Puoi valutare un invio solo mentre è in attesa di valutazione (pending o resubmitted). Le revisioni sono limitate dal limite di revisioni della campagna; dopo di che puoi solo approvare o rifiutare.

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

Risposta · 200

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

Esempio di errore

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

Controlla il tuo saldo

GET/api/v1/balance

available è ciò che puoi spendere per nuove campagne, reserved è trattenuto per le campagne attive, e spent è ciò che hai pagato finora ai lavoratori.

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

Risposta · 200

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

Opzioni e ID

GET/api/v1/options

Elenca le categorie che puoi usare tramite l'API (needs_url e needs_location indicano quali richiedono un link o un luogo), i valori consentiti per targeting e rilascio graduale, e gli ID dei tuoi modelli, gruppi di lavoratori e test di qualifica.

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

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

Errori

La Campaign API usa i codici di stato HTTP. Quando qualcosa va storto, success è false ed error contiene un code da controllare nel tuo codice e un message da mostrare o registrare. I controlli sulle campagne usano gli stessi messaggi della dashboard.

Stato	error.code	Cosa significa
400	`invalid_body, invalid_campaign, invalid_region, category_needs_files, invalid_status, invalid_since, invalid_action, note_required`	Qualcosa nella richiesta manca o non è consentito. message dice cosa.
401	`missing_api_key, invalid_api_key`	Nessuna chiave API, oppure la chiave è errata o è stata sostituita da una più recente.
402	`insufficient_balance`	Il tuo saldo disponibile non copre la campagna. Aggiungi fondi e riprova.
403	`test_key_not_allowed, account_suspended`	Usa la tua chiave API reale. Un account sospeso non può usare l'API.
404	`not_found`	Non esiste nessuna campagna o invio con quell'ID nel tuo account.
409	`already_reviewed, review_refused`	L'invio è già stato valutato, oppure la valutazione non è possibile in questo momento, ad esempio perché è stato raggiunto il limite di revisioni.
429	`rate_limited`	Più di 120 richieste in un minuto. Aspetta il numero di secondi indicato in Retry-After.
500	`internal_error`	Un problema da parte nostra. Riprova, e contatta l'assistenza se continua a succedere.

Test di qualifica esterni

Per i test di qualifica che si svolgono sul tuo sito web.

Comunica il risultato di un test Attiva

GET/api/worker/external_qualification/data

Per i test di qualifica contrassegnati come esterni. Il lavoratore apre il tuo test dal test di qualifica e inserisce il suo token lavoratore sul tuo sito web. Quando finisce, chiama questo endpoint con approve o reject.

Parametro	Descrizione
`qualification_id` obbligatorio	L'ID del tuo test di qualifica
`worker_token` obbligatorio	Il token lavoratore che il lavoratore ha inserito sul tuo sito web
`api_token` obbligatorio	La tua chiave API (la chiave di test per l'endpoint di test)
`decision` obbligatorio	approve o reject

Se il test paga un bonus per il superamento e il tuo saldo committente non può coprirlo, l'invio viene invece salvato come in attesa, così puoi ricaricare il saldo e approvarlo nella dashboard.

Un lavoratore può essere valutato una sola volta per test. Il test deve essere attivo e contrassegnato come esterno, e la chiave API deve appartenere al proprietario del test.

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"

Risposta · 200

{
  "success": true
}

Esempio di errore

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

Testa la tua configurazione

POST/api/worker/external_qualification/data_test

Invia gli stessi campi in JSON all'endpoint di test, con la tua chiave API di test. Non viene salvato nulla e nessun lavoratore è coinvolto: controlla solo la tua richiesta.

Parametro	Descrizione
`qualification_id` obbligatorio	L'ID del tuo test di qualifica
`worker_token` obbligatorio	Il token lavoratore che il lavoratore ha inserito sul tuo sito web
`api_token` obbligatorio	La tua chiave API (la chiave di test per l'endpoint di test)
`decision` obbligatorio	approve o reject

Una chiave di test errata restituisce lo stato 401; campi mancanti o una decisione errata restituiscono lo stato 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"
  }'

Risposta · 200

{
  "success": true
}

Esempio di errore

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

Errori del risultato del test

L'endpoint del risultato risponde sempre con lo stato 200. Controlla success: quando è false, error dice il perché:

error	Cosa significa
`Missing required parameters: qualification_id, worker_token, api_token, decision`	Manca uno dei quattro parametri.
`Decision must be 'approve' or 'reject'`	decision ha un altro valore.
`Invalid API token`	La chiave API è errata o è stata sostituita da una più recente.
`Worker token not found for this qualification`	Il token non appartiene a questo test. Chiedi al lavoratore di controllarlo.
`API token does not belong to the qualification owner`	Usa la chiave dell'account che ha creato il test.
`This qualification is not configured for external submissions`	Il test non è contrassegnato come esterno.
`This qualification is no longer active`	Il test è in pausa o terminato.
`This worker has already been evaluated for this qualification`	Ogni lavoratore riceve un solo risultato per test.
`Worker account is suspended`	Il lavoratore non può svolgere test in questo momento.
`No remaining positions for this qualification`	Tutti i posti del test sono occupati.