DocumentaciónDesarrolladores

API de TaskerData

Publica campañas, recibe los envíos de los trabajadores y revísalos desde tu propio código, o conecta una prueba de calificación externa. Cada solicitud se autentica con tu clave de API.

Resumen

La API de campañas permite que tu código haga lo mismo que haces en el panel de solicitante: crear campañas, seguir su progreso, descargar los envíos con sus pruebas y aprobarlos o rechazarlos. Los endpoints de calificación externa permiten que una prueba en tu propio sitio web le indique a TaskerData si cada trabajador aprobó.

Todas las solicitudes van a https://taskerdata.com por HTTPS. Se envía y se recibe JSON.

Las campañas creadas con la API cuestan lo mismo y siguen las mismas reglas que en el panel. TaskerData las revisa antes de publicarlas (las de los solicitantes de confianza se publican al instante), y el dinero se reserva y se paga de la misma forma.

Autenticación

Abre el panel de solicitante y ve a API. Allí encontrarás dos claves:

Clave de API: para solicitudes reales. La API de campañas la lee del encabezado Authorization. El endpoint de calificación la recibe como api_token.
Clave de API de prueba: solo para el endpoint de prueba de calificación, así puedes probar esa integración sin afectar a trabajadores reales.

Al generar una clave nueva, la anterior se reemplaza al instante, así que actualiza tu backend cuando lo hagas. Puedes generar hasta 3 claves nuevas por hora.

Importante: Mantén tu clave de API en secreto. Úsala solo en tu servidor, nunca en una página web o app que los visitantes puedan abrir.

Envía tu clave de API en cada solicitud a la API de campañas:

Authorization: Bearer YOUR_API_KEY

Puedes hacer hasta 120 solicitudes a la API de campañas por minuto. El encabezado X-RateLimit-Remaining indica cuántas te quedan. Si te pasas, recibes el estado 429, y el encabezado Retry-After indica cuántos segundos debes esperar.

API de campañas

Crea campañas y gestiona el trabajo que reciben desde tu propio código.

Listar campañas

GET/api/v1/campaigns

Tus campañas, de la más reciente a la más antigua. total indica cuántas campañas coinciden, para que puedas recorrerlas con limit y offset.

Parámetros de consulta

Parámetro	Descripción
`status`	Solo campañas con este estado: pending, in review, active, paused, completed, terminated o rejected
`limit`	Cuántas devolver, de 1 a 100 (20 por defecto)
`offset`	Cuántas saltar, para paginar (0 por defecto)

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

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

Ejemplo de error

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

Obtener una campaña

GET/api/v1/campaigns/{id}

Una campaña con su configuración y cuántos envíos están esperando revisión, esperando una revisión del trabajador, aprobados y rechazados. Úsalo para seguir el progreso de una campaña.

En la dirección

Parámetro	Descripción
`id` obligatorio	El ID de la campaña (id en la lista de campañas)

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

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

Ejemplo de error

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

Crear una campaña

POST/api/v1/campaigns

Publica una campaña nueva y reserva su costo total de tu saldo disponible, igual que en el panel. La respuesta incluye el id de la campaña, su costo y su estado: pending mientras TaskerData la revisa, o active al instante si eres un solicitante de confianza.

Cuerpo JSON

Parámetro	Descripción
`title` obligatorio	Título de la campaña, hasta 100 caracteres
`category` obligatorio	Una categoría de GET /api/v1/options. Omítela si usas una plantilla
`instructions` obligatorio	Qué deben hacer los trabajadores, hasta 5000 caracteres
`url`	El enlace que abren los trabajadores. Obligatorio en las categorías donde needs_url es true
`payment` obligatorio	Pago por tarea en USD, como mínimo 0.12
`positions` obligatorio	Cuántos trabajadores, como mínimo 10. Con un archivo de datos de plantilla se calcula a partir de las filas
`time_to_complete` obligatorio	Minutos que tiene un trabajador para terminar, de 1 a 120
`time_to_rate` obligatorio	Días que tienes para revisar cada envío, de 1 a 30. Pasado ese plazo, se aprueba automáticamente
`proof.text`	Pide una respuesta en texto: dile al trabajador qué debe escribir
`proof.images`	Pide capturas de pantalla o fotos: una descripción por imagen
`proof.video`	Pide un video o una grabación: qué debe mostrar
`targeting.region`	international (por defecto), usa, west-europe, east-europe, latin-america o asia-africa
`targeting.exclude_countries`	Nombres de países que quieres dejar fuera de la región
`targeting.min_success_rate`	Tasa de éxito mínima del trabajador: 75 (por defecto), 80, 85, 90, 95 o 100
`targeting.type, targeting.group_id`	Pon type en "group" y group_id en uno de tus grupos de trabajadores para enviar la tarea solo a ese grupo
`qualification_id`	Solo los trabajadores que aprobaron esta prueba de calificación pueden hacer la tarea
`template`	Usa una de tus plantillas en lugar de instrucciones: id, más data con columns y rows que rellenan sus marcadores, una fila por tarea. answers_per_row (de 1 a 5) y rows_per_task (de 1 a 50) son opcionales
`drip_feed`	Libera trabajadores por tandas: min_workers y max_workers (de 1 a 50) e interval_minutes (15, 30, 60, 120, 180, 360, 720 o 1440)
`location`	Para Tareas de campo locales y Cliente misterioso: lat, lng, radius_m (de 50 a 50000) y una address opcional

Por ahora, las categorías que necesitan archivos que subes (como Transcripción de audio o Etiquetado de imágenes), las tareas de video y las imágenes de ejemplo solo se pueden crear en el panel. La guía Costos y comisiones explica cómo se calcula el precio.

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

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

Ejemplo de error

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

Obtener envíos

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

El trabajo que los trabajadores enviaron para una campaña, del más antiguo al más reciente, con sus pruebas: la respuesta en texto, los enlaces a imágenes y video, las respuestas de la plantilla (answers), la fila de datos en la que trabajaron y, en las tareas de campo, su ubicación.

En la dirección

Parámetro	Descripción
`id` obligatorio	El ID de la campaña (id en la lista de campañas)

Parámetros de consulta

Parámetro	Descripción
`status`	to_review (pending y resubmitted), pending, resubmitted, revision_requested, approved o rejected
`since`	Solo envíos enviados en este momento o después, por ejemplo 2026-10-01T00:00:00Z
`after_id`	Para paginar: solo envíos con un id mayor. Usa next_after_id de la página anterior
`limit`	Cuántos devolver, de 1 a 100 (50 por defecto)

Para recoger trabajo nuevo con regularidad, guarda el último id que recibiste y envíalo como after_id la próxima vez. raw contiene todo lo que envió el trabajador, por si necesitas algo que no aparece en la lista.

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

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

Ejemplo de error

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

Revisar un envío

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

Aprueba, rechaza o pide una revisión, igual que con los botones del panel. Al aprobar, se le paga al trabajador con el dinero reservado. Al rechazar, el pago y su comisión vuelven a tu saldo y la plaza queda libre para otro trabajador.

En la dirección

Parámetro	Descripción
`id` obligatorio	El ID del envío

Cuerpo JSON

Parámetro	Descripción
`action` obligatorio	approve, reject o revision
`reason`	Con reject: el motivo que ve el trabajador
`note`	Con revision (obligatorio): qué debe corregir el trabajador

Solo puedes revisar un envío mientras está esperando revisión (pending o resubmitted). Las revisiones están limitadas por el límite de revisiones de la campaña; después solo puedes aprobar o rechazar.

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

Respuesta · 200

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

Ejemplo de error

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

Consultar tu saldo

GET/api/v1/balance

available es lo que puedes gastar en campañas nuevas, reserved es lo que está retenido para campañas activas, y spent es lo que has pagado a los trabajadores hasta ahora.

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

Respuesta · 200

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

Opciones e IDs

GET/api/v1/options

Muestra las categorías que puedes usar con la API (needs_url y needs_location indican cuáles necesitan un enlace o una ubicación), los valores permitidos de segmentación y goteo, y los IDs de tus plantillas, grupos de trabajadores y pruebas de calificación.

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

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

Errores

La API de campañas usa códigos de estado HTTP. Cuando algo sale mal, success es false y error incluye un code para comprobar en tu código y un message para mostrar o registrar. Las comprobaciones de campañas usan los mismos mensajes que el panel.

Estado	error.code	Qué significa
400	`invalid_body, invalid_campaign, invalid_region, category_needs_files, invalid_status, invalid_since, invalid_action, note_required`	Falta algo en la solicitud o no está permitido. message indica qué.
401	`missing_api_key, invalid_api_key`	No hay clave de API, o la clave es incorrecta o fue reemplazada por una más reciente.
402	`insufficient_balance`	Tu saldo disponible no cubre la campaña. Añade fondos y vuelve a intentarlo.
403	`test_key_not_allowed, account_suspended`	Usa tu clave de API real. Una cuenta suspendida no puede usar la API.
404	`not_found`	No hay ninguna campaña ni envío con ese ID en tu cuenta.
409	`already_reviewed, review_refused`	El envío ya se revisó, o la revisión no es posible en este momento, por ejemplo porque se alcanzó el límite de revisiones.
429	`rate_limited`	Más de 120 solicitudes en un minuto. Espera los segundos que indica Retry-After.
500	`internal_error`	Un problema de nuestro lado. Vuelve a intentarlo y contacta con soporte si sigue pasando.

Pruebas de calificación externas

Para pruebas de calificación que se hacen en tu propio sitio web.

Enviar el resultado de una prueba Activo

GET/api/worker/external_qualification/data

Para pruebas de calificación marcadas como externas. El trabajador abre tu prueba desde la calificación e introduce su token de trabajador en tu sitio web. Cuando termine, llama a este endpoint con approve o reject.

Parámetro	Descripción
`qualification_id` obligatorio	El ID de tu prueba de calificación
`worker_token` obligatorio	El token de trabajador que el trabajador introdujo en tu sitio web
`api_token` obligatorio	Tu clave de API (la clave de prueba para el endpoint de prueba)
`decision` obligatorio	approve o reject

Si la prueba paga una bonificación por aprobar y tu saldo de solicitante no alcanza para cubrirla, el envío se guarda como pendiente, para que puedas recargar y aprobarlo desde el panel.

Cada trabajador solo puede ser evaluado una vez por prueba. La prueba debe estar activa y marcada como externa, y la clave de API debe pertenecer al dueño de la prueba.

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"

Respuesta · 200

{
  "success": true
}

Ejemplo de error

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

Prueba tu configuración

POST/api/worker/external_qualification/data_test

Envía los mismos campos como JSON al endpoint de prueba, con tu clave de API de prueba. No se guarda nada ni se afecta a ningún trabajador: solo se comprueba tu solicitud.

Parámetro	Descripción
`qualification_id` obligatorio	El ID de tu prueba de calificación
`worker_token` obligatorio	El token de trabajador que el trabajador introdujo en tu sitio web
`api_token` obligatorio	Tu clave de API (la clave de prueba para el endpoint de prueba)
`decision` obligatorio	approve o reject

Una clave de prueba incorrecta devuelve el estado 401; si faltan campos o decision es incorrecto, devuelve el estado 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"
  }'

Respuesta · 200

{
  "success": true
}

Ejemplo de error

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

Errores de resultados de pruebas

El endpoint de resultados siempre responde con el estado 200. Revisa success: cuando es false, error indica el motivo:

error	Qué significa
`Missing required parameters: qualification_id, worker_token, api_token, decision`	Falta uno de los cuatro parámetros.
`Decision must be 'approve' or 'reject'`	decision tiene otro valor.
`Invalid API token`	La clave de API es incorrecta o fue reemplazada por una más reciente.
`Worker token not found for this qualification`	El token no pertenece a esta prueba. Pídele al trabajador que lo revise.
`API token does not belong to the qualification owner`	Usa la clave de la cuenta que creó la prueba.
`This qualification is not configured for external submissions`	La prueba no está marcada como externa.
`This qualification is no longer active`	La prueba está en pausa o finalizada.
`This worker has already been evaluated for this qualification`	Cada trabajador recibe un solo resultado por prueba.
`Worker account is suspended`	El trabajador no puede hacer pruebas en este momento.
`No remaining positions for this qualification`	Todas las plazas de la prueba están ocupadas.