DocumentaçãoDesenvolvedores

API da TaskerData

Publique campanhas, receba os envios dos trabalhadores e avalie-os a partir do seu próprio código, ou conecte um teste de qualificação externo. Toda requisição é autenticada com a sua chave de API.

Visão geral

A API de campanhas permite que o seu código faça o mesmo que você faz no painel de solicitante: criar campanhas, acompanhar o andamento, baixar os envios com seus comprovantes e aprová-los ou rejeitá-los. Os endpoints de qualificação externa permitem que um teste no seu próprio site informe à TaskerData se cada trabalhador foi aprovado.

Todas as requisições vão para https://taskerdata.com via HTTPS. Envie e receba JSON.

Campanhas criadas pela API custam o mesmo e seguem as mesmas regras do painel. A TaskerData as revisa antes de entrarem no ar (solicitantes confiáveis entram no ar na hora), e o dinheiro é reservado e pago da mesma forma.

Autenticação

Abra o painel de solicitante e vá até API. Lá você encontra duas chaves:

Chave de API: para requisições reais. A API de campanhas a lê do header Authorization. O endpoint de qualificação a recebe como api_token.
Chave de API de teste: só para o endpoint de teste de qualificação, para você testar essa integração sem afetar trabalhadores reais.

Gerar uma nova chave substitui a antiga na mesma hora, então atualize seu backend quando fizer isso. Você pode gerar até 3 novas chaves por hora.

Importante: Mantenha sua chave de API em segredo. Use-a apenas no seu servidor, nunca em uma página web ou app que os visitantes possam abrir.

Envie sua chave de API em toda requisição à API de campanhas:

Authorization: Bearer YOUR_API_KEY

Você pode fazer até 120 requisições à API de campanhas por minuto. O header X-RateLimit-Remaining mostra quantas ainda restam. Depois disso, você recebe o status 429, e o header Retry-After informa quantos segundos esperar.

API de campanhas

Crie campanhas e gerencie o trabalho que elas recebem, a partir do seu próprio código.

Listar campanhas

GET/api/v1/campaigns

Suas campanhas, das mais novas para as mais antigas. total é quantas campanhas correspondem ao filtro, para você paginar com limit e offset.

Parâmetros de consulta

Parâmetro	Descrição
`status`	Só campanhas com este status: pending, in review, active, paused, completed, terminated ou rejected
`limit`	Quantas retornar, de 1 a 100 (padrão 20)
`offset`	Quantas pular, para paginação (padrão 0)

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

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

Exemplo de erro

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

Obter uma campanha

GET/api/v1/campaigns/{id}

Uma campanha com suas configurações e quantos envios estão aguardando avaliação, aguardando revisão, aprovados e rejeitados. Use para acompanhar o andamento de uma campanha.

No endereço

Parâmetro	Descrição
`id` obrigatório	O ID da campanha (id na lista de campanhas)

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

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

Exemplo de erro

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

Criar uma campanha

POST/api/v1/campaigns

Publica uma nova campanha e reserva o custo total do seu saldo disponível, exatamente como o painel. A resposta inclui o id da campanha, o custo e o status: pending enquanto a TaskerData a revisa, ou active na hora se você for um solicitante confiável.

Corpo JSON

Parâmetro	Descrição
`title` obrigatório	Título da campanha, até 100 caracteres
`category` obrigatório	Uma categoria de GET /api/v1/options. Deixe de fora quando usar um modelo
`instructions` obrigatório	O que os trabalhadores devem fazer, até 5.000 caracteres
`url`	O link que os trabalhadores abrem. Obrigatório nas categorias em que needs_url é true
`payment` obrigatório	Pagamento por tarefa em USD, no mínimo 0.12
`positions` obrigatório	Quantos trabalhadores, no mínimo 10. Com um arquivo de dados de modelo, é calculado a partir das linhas
`time_to_complete` obrigatório	Minutos que o trabalhador tem para terminar, de 1 a 120
`time_to_rate` obrigatório	Dias que você tem para avaliar cada envio, de 1 a 30. Depois disso, ele é aprovado automaticamente
`proof.text`	Peça uma resposta em texto: diga ao trabalhador o que escrever
`proof.images`	Peça capturas de tela ou fotos: uma descrição por imagem
`proof.video`	Peça um vídeo ou uma gravação: o que ele deve mostrar
`targeting.region`	international (padrão), usa, west-europe, east-europe, latin-america ou asia-africa
`targeting.exclude_countries`	Nomes de países a deixar de fora da região
`targeting.min_success_rate`	Taxa de sucesso mínima do trabalhador: 75 (padrão), 80, 85, 90, 95 ou 100
`targeting.type, targeting.group_id`	Defina type como "group" e group_id como um dos seus grupos de trabalhadores para enviar a tarefa só para esse grupo
`qualification_id`	Só trabalhadores aprovados neste teste de qualificação podem fazer a tarefa
`template`	Use um dos seus modelos em vez de instruções: id, mais data com columns e rows que preenchem os placeholders dele, uma linha por tarefa. answers_per_row (1 a 5) e rows_per_task (1 a 50) são opcionais
`drip_feed`	Libere trabalhadores em lotes: min_workers e max_workers (1 a 50) e interval_minutes (15, 30, 60, 120, 180, 360, 720 ou 1440)
`location`	Para Tarefas de campo locais e Cliente oculto: lat, lng, radius_m (50 a 50.000) e um address opcional

Por enquanto, categorias que precisam de arquivos enviados por você (como Transcrição de áudio ou Marcação de imagens), tarefas de vídeo e imagens de exemplo só podem ser criadas no painel. O guia Custos e taxas explica como o preço é calculado.

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

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

Exemplo de erro

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

Obter envios

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

O trabalho que os trabalhadores enviaram para uma campanha, dos mais antigos para os mais novos, com os comprovantes: a resposta em texto, links para imagens e vídeo, as respostas do modelo (answers), a linha de dados em que trabalharam e, em tarefas de campo, a localização.

No endereço

Parâmetro	Descrição
`id` obrigatório	O ID da campanha (id na lista de campanhas)

Parâmetros de consulta

Parâmetro	Descrição
`status`	to_review (pending e resubmitted), pending, resubmitted, revision_requested, approved ou rejected
`since`	Só envios feitos a partir deste momento, por exemplo 2026-10-01T00:00:00Z
`after_id`	Para paginação: só envios com id maior. Use next_after_id da página anterior
`limit`	Quantos retornar, de 1 a 100 (padrão 50)

Para buscar trabalhos novos regularmente, guarde o último id recebido e envie-o como after_id na próxima vez. raw traz tudo o que o trabalhador enviou, caso você precise de algo que não esteja listado.

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

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

Exemplo de erro

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

Avaliar um envio

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

Aprove, rejeite ou peça uma revisão, como nos botões do painel. Aprovar paga o trabalhador com o dinheiro reservado. Rejeitar devolve o pagamento e a taxa correspondente ao seu saldo e libera a vaga para outro trabalhador.

No endereço

Parâmetro	Descrição
`id` obrigatório	O ID do envio

Corpo JSON

Parâmetro	Descrição
`action` obrigatório	approve, reject ou revision
`reason`	Com reject: o motivo que o trabalhador vê
`note`	Com revision (obrigatório): o que o trabalhador deve corrigir

Você só pode avaliar um envio enquanto ele aguarda avaliação (pending ou resubmitted). As revisões são limitadas pelo limite de revisões da campanha; depois disso, você só pode aprovar ou rejeitar.

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

Resposta · 200

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

Exemplo de erro

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

Consultar seu saldo

GET/api/v1/balance

available é o que você pode gastar em novas campanhas, reserved é o valor reservado para campanhas ativas e spent é o que você já pagou aos trabalhadores até agora.

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

Resposta · 200

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

Opções e IDs

GET/api/v1/options

Lista as categorias que você pode usar pela API (needs_url e needs_location mostram quais precisam de um link ou de uma localização), os valores permitidos de segmentação e de liberação gradual, e os IDs dos seus modelos, grupos de trabalhadores e testes de qualificação.

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

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

Erros

A API de campanhas usa códigos de status HTTP. Quando algo dá errado, success é false e error traz um code para verificar no seu código e uma message para mostrar ou registrar. As verificações de campanha usam as mesmas mensagens do painel.

Status	error.code	O que significa
400	`invalid_body, invalid_campaign, invalid_region, category_needs_files, invalid_status, invalid_since, invalid_action, note_required`	Algo na requisição está faltando ou não é permitido. message diz o quê.
401	`missing_api_key, invalid_api_key`	Sem chave de API, ou a chave está errada ou foi substituída por uma mais nova.
402	`insufficient_balance`	Seu saldo disponível não cobre a campanha. Adicione fundos e tente de novo.
403	`test_key_not_allowed, account_suspended`	Use sua chave de API real. Uma conta suspensa não pode usar a API.
404	`not_found`	Não existe campanha ou envio com esse ID na sua conta.
409	`already_reviewed, review_refused`	O envio já foi avaliado, ou a avaliação não é possível agora, por exemplo porque o limite de revisões foi atingido.
429	`rate_limited`	Mais de 120 requisições em um minuto. Espere o número de segundos indicado em Retry-After.
500	`internal_error`	Um problema do nosso lado. Tente de novo e fale com o suporte se continuar acontecendo.

Testes de qualificação externos

Para testes de qualificação que rodam no seu próprio site.

Enviar o resultado de um teste Ativo

GET/api/worker/external_qualification/data

Para testes de qualificação marcados como externos. O trabalhador abre o seu teste a partir da qualificação e informa o token de trabalhador dele no seu site. Quando ele terminar, chame este endpoint com approve ou reject.

Parâmetro	Descrição
`qualification_id` obrigatório	O ID do seu teste de qualificação
`worker_token` obrigatório	O token de trabalhador que o trabalhador informou no seu site
`api_token` obrigatório	Sua chave de API (a chave de teste para o endpoint de teste)
`decision` obrigatório	approve ou reject

Se o teste paga um bônus pela aprovação e o seu saldo de solicitante não cobre o valor, o envio fica salvo como pendente, para você recarregar o saldo e aprová-lo no painel.

Cada trabalhador pode ser avaliado uma vez por teste. O teste precisa estar ativo e marcado como externo, e a chave de API precisa pertencer ao dono do teste.

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"

Resposta · 200

{
  "success": true
}

Exemplo de erro

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

Testar sua integração

POST/api/worker/external_qualification/data_test

Envie os mesmos campos em JSON para o endpoint de teste, com a sua chave de API de teste. Nada é salvo e nenhum trabalhador é afetado: ele apenas verifica a sua requisição.

Parâmetro	Descrição
`qualification_id` obrigatório	O ID do seu teste de qualificação
`worker_token` obrigatório	O token de trabalhador que o trabalhador informou no seu site
`api_token` obrigatório	Sua chave de API (a chave de teste para o endpoint de teste)
`decision` obrigatório	approve ou reject

Uma chave de teste errada retorna o status 401; campos faltando ou um valor de decision inválido retornam o 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"
  }'

Resposta · 200

{
  "success": true
}

Exemplo de erro

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

Erros de resultado de teste

O endpoint de resultado sempre responde com status 200. Verifique success: quando for false, error explica o motivo:

error	O que significa
`Missing required parameters: qualification_id, worker_token, api_token, decision`	Falta um dos quatro parâmetros.
`Decision must be 'approve' or 'reject'`	decision tem outro valor.
`Invalid API token`	A chave de API está errada ou foi substituída por uma mais nova.
`Worker token not found for this qualification`	O token não pertence a este teste. Peça ao trabalhador para conferi-lo.
`API token does not belong to the qualification owner`	Use a chave da conta que criou o teste.
`This qualification is not configured for external submissions`	O teste não está marcado como externo.
`This qualification is no longer active`	O teste está pausado ou foi encerrado.
`This worker has already been evaluated for this qualification`	Cada trabalhador recebe um único resultado por teste.
`Worker account is suspended`	O trabalhador não pode fazer testes no momento.
`No remaining positions for this qualification`	Todas as vagas do teste já foram preenchidas.