GuidesDéveloppeurs

API TaskerData

Publiez des campagnes, récupérez les soumissions des travailleurs et vérifiez-les depuis votre propre code, ou connectez un test de qualification externe. Chaque requête est authentifiée avec votre clé API.

Vue d'ensemble

L'API Campagnes permet à votre code de faire ce que vous faites dans le tableau de bord demandeur : créer des campagnes, suivre leur avancement, télécharger les soumissions avec leurs preuves et les approuver ou les refuser. Les endpoints de qualification externe permettent à un test hébergé sur votre site d'indiquer à TaskerData si chaque travailleur l'a réussi.

Toutes les requêtes sont envoyées à https://taskerdata.com en HTTPS. Les données sont envoyées et reçues au format JSON.

Les campagnes créées via l'API coûtent le même prix et suivent les mêmes règles que dans le tableau de bord. TaskerData les examine avant leur mise en ligne (les campagnes des demandeurs de confiance sont mises en ligne immédiatement), et l'argent est réservé et versé de la même façon.

Authentification

Ouvrez le tableau de bord demandeur et allez dans API. Vous y trouverez deux clés :

Clé API : pour les vraies requêtes. L'API Campagnes la lit dans l'en-tête Authorization. L'endpoint de qualification la reçoit dans api_token.
Clé API de test : uniquement pour l'endpoint de test des qualifications, pour essayer cette intégration sans toucher aux vrais travailleurs.

Générer une nouvelle clé remplace immédiatement l'ancienne : pensez à mettre à jour votre backend. Vous pouvez générer jusqu'à 3 nouvelles clés par heure.

Important : Gardez votre clé API secrète. Utilisez-la uniquement sur votre serveur, jamais dans une page web ou une application accessible aux visiteurs.

Envoyez votre clé API avec chaque requête à l'API Campagnes :

Authorization: Bearer YOUR_API_KEY

Vous pouvez envoyer jusqu'à 120 requêtes par minute à l'API Campagnes. L'en-tête X-RateLimit-Remaining indique combien il vous en reste. Au-delà, vous recevez le statut 429, et l'en-tête Retry-After indique combien de secondes attendre.

API Campagnes

Créez des campagnes et gérez le travail qu'elles reçoivent, depuis votre propre code.

Lister les campagnes

GET/api/v1/campaigns

Vos campagnes, des plus récentes aux plus anciennes. total indique le nombre de campagnes correspondantes, pour que vous puissiez les parcourir page par page avec limit et offset.

Paramètres de requête

Paramètre	Description
`status`	Uniquement les campagnes ayant ce statut : pending, in review, active, paused, completed, terminated ou rejected
`limit`	Nombre de résultats à renvoyer, de 1 à 100 (20 par défaut)
`offset`	Nombre de résultats à ignorer, pour la pagination (0 par défaut)

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

Réponse · 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
}

Exemple d'erreur

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

Obtenir une campagne

GET/api/v1/campaigns/{id}

Une campagne avec ses réglages et le nombre de soumissions en attente d'évaluation, en attente de révision, approuvées et refusées. Utilisez-le pour suivre l'avancement d'une campagne.

Dans l'adresse

Paramètre	Description
`id` obligatoire	L'ID de la campagne (id dans la liste des campagnes)

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

Réponse · 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
    }
  }
}

Exemple d'erreur

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

Créer une campagne

POST/api/v1/campaigns

Publie une nouvelle campagne et réserve son coût total sur votre solde disponible, exactement comme le tableau de bord. La réponse contient l'id de la campagne, son coût et son statut : pending pendant que TaskerData l'examine, ou active immédiatement si vous êtes un demandeur de confiance.

Corps JSON

Paramètre	Description
`title` obligatoire	Titre de la campagne, 100 caractères maximum
`category` obligatoire	Une catégorie issue de GET /api/v1/options. Ne l'indiquez pas si vous utilisez un modèle
`instructions` obligatoire	Ce que les travailleurs doivent faire, 5 000 caractères maximum
`url`	Le lien que les travailleurs ouvrent. Obligatoire pour les catégories où needs_url vaut true
`payment` obligatoire	Paiement par tâche en USD, au moins 0.12
`positions` obligatoire	Nombre de travailleurs, au moins 10. Avec un fichier de données de modèle, il est calculé à partir des lignes
`time_to_complete` obligatoire	Minutes dont dispose un travailleur pour terminer, de 1 à 120
`time_to_rate` obligatoire	Jours dont vous disposez pour évaluer chaque soumission, de 1 à 30. Passé ce délai, elle est approuvée automatiquement
`proof.text`	Demander une réponse écrite : indiquez au travailleur ce qu'il doit écrire
`proof.images`	Demander des captures d'écran ou des photos : une description par image
`proof.video`	Demander une vidéo ou un enregistrement : ce qu'il doit montrer
`targeting.region`	international (par défaut), usa, west-europe, east-europe, latin-america ou asia-africa
`targeting.exclude_countries`	Noms des pays à exclure de la région
`targeting.min_success_rate`	Taux de réussite minimum des travailleurs : 75 (par défaut), 80, 85, 90, 95 ou 100
`targeting.type, targeting.group_id`	Définissez type sur "group" et group_id sur l'un de vos groupes de travailleurs pour n'envoyer la tâche qu'à ce groupe
`qualification_id`	Seuls les travailleurs ayant réussi ce test de qualification peuvent faire la tâche
`template`	Utilisez l'un de vos modèles au lieu d'instructions : id, plus data avec des colonnes (columns) et des lignes (rows) qui remplissent ses repères, une ligne par tâche. answers_per_row (1 à 5) et rows_per_task (1 à 50) sont facultatifs
`drip_feed`	Diffuser les places par vagues : min_workers et max_workers (1 à 50) et interval_minutes (15, 30, 60, 120, 180, 360, 720 ou 1440)
`location`	Pour Tâches de terrain locales et Client mystère : lat, lng, radius_m (50 à 50 000) et une adresse facultative (address)

Pour l'instant, les catégories qui nécessitent des fichiers à envoyer (comme Transcription audio ou Étiquetage d'images), les tâches vidéo et les images d'exemple ne peuvent être créées que dans le tableau de bord. Le guide Coûts et frais explique comment le prix est calculé.

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éponse · 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
  }
}

Exemple d'erreur

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

Récupérer les soumissions

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

Le travail envoyé par les travailleurs pour une campagne, des plus anciens aux plus récents, avec leurs preuves : la réponse écrite, les liens vers les images et la vidéo, les réponses au modèle (answers), la ligne de données traitée et, pour les tâches de terrain, leur position.

Dans l'adresse

Paramètre	Description
`id` obligatoire	L'ID de la campagne (id dans la liste des campagnes)

Paramètres de requête

Paramètre	Description
`status`	to_review (pending et resubmitted), pending, resubmitted, revision_requested, approved ou rejected
`since`	Uniquement les soumissions envoyées à partir de ce moment, par exemple 2026-10-01T00:00:00Z
`after_id`	Pour la pagination : uniquement les soumissions avec un id plus élevé. Utilisez le next_after_id de la page précédente
`limit`	Nombre de résultats à renvoyer, de 1 à 100 (50 par défaut)

Pour récupérer régulièrement le nouveau travail, gardez le dernier id reçu et envoyez-le dans after_id la fois suivante. raw contient tout ce que le travailleur a envoyé, au cas où vous auriez besoin d'une information qui n'est pas listée.

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

Réponse · 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
}

Exemple d'erreur

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

Évaluer une soumission

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

Approuvez, refusez ou demandez une révision, comme avec les boutons du tableau de bord. Approuver paie le travailleur avec l'argent réservé. Refuser rend le paiement et ses frais à votre solde et libère la place pour un autre travailleur.

Dans l'adresse

Paramètre	Description
`id` obligatoire	L'ID de la soumission

Corps JSON

Paramètre	Description
`action` obligatoire	approve, reject ou revision
`reason`	Avec reject : la raison que voit le travailleur
`note`	Avec revision (obligatoire) : ce que le travailleur doit corriger

Vous ne pouvez évaluer une soumission que lorsqu'elle attend une évaluation (pending ou resubmitted). Les révisions sont limitées par la limite de révisions de la campagne ; une fois celle-ci atteinte, vous pouvez seulement approuver ou refuser.

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éponse · 200

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

Exemple d'erreur

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

Consulter votre solde

GET/api/v1/balance

available est ce que vous pouvez dépenser pour de nouvelles campagnes, reserved est bloqué pour les campagnes en ligne, et spent est ce que vous avez versé aux travailleurs jusqu'ici.

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

Réponse · 200

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

Options et ID

GET/api/v1/options

Liste les catégories utilisables via l'API (needs_url et needs_location indiquent celles qui nécessitent un lien ou une position), les valeurs autorisées pour le ciblage et la diffusion progressive, ainsi que les ID de vos modèles, groupes de travailleurs et tests de qualification.

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

Réponse · 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"
    }
  ]
}

Erreurs

L'API Campagnes utilise les codes de statut HTTP. En cas de problème, success vaut false et error contient un code (code) à vérifier dans votre code et un message (message) à afficher ou à journaliser. Les vérifications de campagne utilisent les mêmes messages que le tableau de bord.

Statut	error.code	Signification
400	`invalid_body, invalid_campaign, invalid_region, category_needs_files, invalid_status, invalid_since, invalid_action, note_required`	Un élément de la requête est manquant ou non autorisé. message précise lequel.
401	`missing_api_key, invalid_api_key`	Aucune clé API, ou la clé est incorrecte ou a été remplacée par une plus récente.
402	`insufficient_balance`	Votre solde disponible ne couvre pas la campagne. Ajoutez des fonds et réessayez.
403	`test_key_not_allowed, account_suspended`	Utilisez votre clé API réelle. Un compte suspendu ne peut pas utiliser l'API.
404	`not_found`	Aucune campagne ni soumission avec cet ID dans votre compte.
409	`already_reviewed, review_refused`	La soumission a déjà été évaluée, ou l'évaluation n'est pas possible pour le moment, par exemple parce que la limite de révisions est atteinte.
429	`rate_limited`	Plus de 120 requêtes en une minute. Attendez le nombre de secondes indiqué dans Retry-After.
500	`internal_error`	Un problème de notre côté. Réessayez, et contactez le support si le problème persiste.

Tests de qualification externes

Pour les tests de qualification qui se déroulent sur votre propre site.

Transmettre un résultat de test En ligne

GET/api/worker/external_qualification/data

Pour les tests de qualification marqués comme externes. Le travailleur ouvre votre test depuis la qualification et saisit son jeton de travailleur sur votre site. Quand il a terminé, appelez cet endpoint avec approve ou reject.

Paramètre	Description
`qualification_id` obligatoire	L'ID de votre test de qualification
`worker_token` obligatoire	Le jeton que le travailleur a saisi sur votre site
`api_token` obligatoire	Votre clé API (la clé de test pour l'endpoint de test)
`decision` obligatoire	approve ou reject

Si le test verse un bonus en cas de réussite et que votre solde demandeur ne suffit pas à le couvrir, la soumission est enregistrée en attente : vous pouvez alors recharger votre solde et l'approuver depuis le tableau de bord.

Un travailleur ne peut être évalué qu'une fois par test. Le test doit être actif et marqué comme externe, et la clé API doit appartenir au propriétaire du 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"

Réponse · 200

{
  "success": true
}

Exemple d'erreur

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

Tester votre intégration

POST/api/worker/external_qualification/data_test

Envoyez les mêmes champs en JSON à l'endpoint de test, avec votre clé API de test. Rien n'est enregistré et aucun travailleur n'est concerné : seule votre requête est vérifiée.

Paramètre	Description
`qualification_id` obligatoire	L'ID de votre test de qualification
`worker_token` obligatoire	Le jeton que le travailleur a saisi sur votre site
`api_token` obligatoire	Votre clé API (la clé de test pour l'endpoint de test)
`decision` obligatoire	approve ou reject

Une mauvaise clé de test renvoie le statut 401 ; des champs manquants ou une valeur de decision incorrecte renvoient le statut 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éponse · 200

{
  "success": true
}

Exemple d'erreur

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

Erreurs des résultats de test

L'endpoint de résultat répond toujours avec le statut 200. Vérifiez success : s'il vaut false, error en donne la raison :

error	Signification
`Missing required parameters: qualification_id, worker_token, api_token, decision`	L'un des quatre paramètres est manquant.
`Decision must be 'approve' or 'reject'`	decision a une autre valeur.
`Invalid API token`	La clé API est incorrecte ou a été remplacée par une plus récente.
`Worker token not found for this qualification`	Le jeton n'appartient pas à ce test. Demandez au travailleur de le vérifier.
`API token does not belong to the qualification owner`	Utilisez la clé du compte qui a créé le test.
`This qualification is not configured for external submissions`	Le test n'est pas marqué comme externe.
`This qualification is no longer active`	Le test est en pause ou terminé.
`This worker has already been evaluated for this qualification`	Chaque travailleur reçoit un seul résultat par test.
`Worker account is suspended`	Le travailleur ne peut pas passer de test pour le moment.
`No remaining positions for this qualification`	Toutes les places du test sont prises.