DokumentacjaDla programistów

API TaskerData

Twórz kampanie, zbieraj zgłoszenia wykonawców i oceniaj je z własnego kodu albo podłącz zewnętrzny test kwalifikacyjny. Każde żądanie jest uwierzytelniane twoim kluczem API.

Przegląd

Campaign API pozwala twojemu kodowi robić to, co robisz w panelu zleceniodawcy: tworzyć kampanie, śledzić ich postęp, pobierać zgłoszenia z dowodami oraz je zatwierdzać lub odrzucać. Endpointy kwalifikacji zewnętrznych pozwalają testowi na twojej stronie informować TaskerData, czy każdy wykonawca zdał.

Wszystkie żądania trafiają na https://taskerdata.com przez HTTPS. Wysyłaj i odbieraj JSON.

Kampanie utworzone przez API kosztują tyle samo i podlegają tym samym zasadom co w panelu. TaskerData sprawdza je przed publikacją (kampanie zaufanych zleceniodawców startują od razu), a pieniądze są rezerwowane i wypłacane w ten sam sposób.

Uwierzytelnianie

Otwórz panel zleceniodawcy i przejdź do sekcji API. Znajdziesz tam dwa klucze:

Klucz API: do prawdziwych żądań. Campaign API odczytuje go z nagłówka Authorization. Endpoint kwalifikacji przyjmuje go jako api_token.
Testowy klucz API: tylko do testowego endpointu kwalifikacji, abyś mógł wypróbować integrację bez wpływu na prawdziwych wykonawców.

Wygenerowanie nowego klucza od razu zastępuje stary, więc zaktualizuj wtedy backend. Możesz wygenerować do 3 nowych kluczy na godzinę.

Ważne: Zachowaj klucz API w tajemnicy. Używaj go tylko na serwerze, nigdy na stronie internetowej ani w aplikacji, którą mogą otworzyć odwiedzający.

Wysyłaj klucz API z każdym żądaniem Campaign API:

Authorization: Bearer YOUR_API_KEY

Możesz wysłać do 120 żądań Campaign API na minutę. Nagłówek X-RateLimit-Remaining pokazuje, ile zostało. Po przekroczeniu limitu otrzymasz status 429, a nagłówek Retry-After poda, ile sekund odczekać.

Campaign API

Twórz kampanie i obsługuj pracę, którą przynoszą, z własnego kodu.

Lista kampanii

GET/api/v1/campaigns

Twoje kampanie, od najnowszych. total to liczba pasujących kampanii, więc możesz je stronicować za pomocą limit i offset.

Parametry zapytania

Parametr	Opis
`status`	Tylko kampanie z tym statusem: pending, in review, active, paused, completed, terminated lub rejected
`limit`	Ile zwrócić, od 1 do 100 (domyślnie 20)
`offset`	Ile pominąć, do stronicowania (domyślnie 0)

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

Odpowiedź · 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
}

Przykład błędu

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

Pobierz kampanię

GET/api/v1/campaigns/{id}

Jedna kampania z ustawieniami i liczbą zgłoszeń czekających na ocenę, czekających na poprawkę, zatwierdzonych i odrzuconych. Użyj tego, aby śledzić postęp kampanii.

W adresie

Parametr	Opis
`id` wymagany	ID kampanii (id na liście kampanii)

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

Odpowiedź · 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
    }
  }
}

Przykład błędu

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

Utwórz kampanię

POST/api/v1/campaigns

Tworzy nową kampanię i rezerwuje jej pełny koszt z dostępnego salda, dokładnie tak jak w panelu. Odpowiedź zawiera id kampanii, jej koszt i status: pending, gdy TaskerData ją sprawdza, lub od razu active, jeśli jesteś zaufanym zleceniodawcą.

Treść JSON

Parametr	Opis
`title` wymagany	Tytuł kampanii, do 100 znaków
`category` wymagany	Kategoria z GET /api/v1/options. Pomiń ją, gdy używasz szablonu
`instructions` wymagany	Co mają zrobić wykonawcy, do 5000 znaków
`url`	Link, który otwierają wykonawcy. Wymagany w kategoriach, w których needs_url ma wartość true
`payment` wymagany	Wynagrodzenie za zadanie w USD, co najmniej 0.12
`positions` wymagany	Ilu wykonawców, co najmniej 10. Przy pliku danych szablonu wynika z liczby wierszy
`time_to_complete` wymagany	Ile minut ma wykonawca na wykonanie, od 1 do 120
`time_to_rate` wymagany	Ile dni masz na ocenę każdego zgłoszenia, od 1 do 30. Potem jest zatwierdzane automatycznie
`proof.text`	Poproś o odpowiedź tekstową: napisz wykonawcy, co ma wpisać
`proof.images`	Poproś o zrzuty ekranu lub zdjęcia: jeden opis na obraz
`proof.video`	Poproś o wideo lub nagranie: co ma pokazywać
`targeting.region`	international (domyślnie), usa, west-europe, east-europe, latin-america lub asia-africa
`targeting.exclude_countries`	Nazwy krajów do wyłączenia z regionu
`targeting.min_success_rate`	Minimalny wskaźnik sukcesu wykonawcy: 75 (domyślnie), 80, 85, 90, 95 lub 100
`targeting.type, targeting.group_id`	Ustaw type na "group" i group_id na jedną ze swoich grup wykonawców, aby wysłać zadanie tylko do tej grupy
`qualification_id`	Zadanie mogą wziąć tylko wykonawcy, którzy zdali ten test kwalifikacyjny
`template`	Użyj jednego ze swoich szablonów zamiast instrukcji: id oraz data z kolumnami i wierszami, które wypełniają jego symbole zastępcze, jeden wiersz na zadanie. answers_per_row (od 1 do 5) i rows_per_task (od 1 do 50) są opcjonalne
`drip_feed`	Udostępniaj wykonawcom partiami: min_workers i max_workers (od 1 do 50) oraz interval_minutes (15, 30, 60, 120, 180, 360, 720 lub 1440)
`location`	Dla Lokalnych zadań terenowych i Tajemniczego klienta: lat, lng, radius_m (od 50 do 50 000) i opcjonalnie address

Na razie kategorie wymagające przesyłanych plików (np. Transkrypcja audio lub Oznaczanie obrazów), zadania wideo i przykładowe obrazy można tworzyć tylko w panelu. Poradnik Koszty i opłaty wyjaśnia, jak obliczana jest cena.

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

Odpowiedź · 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
  }
}

Przykład błędu

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

Pobierz zgłoszenia

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

Praca przesłana przez wykonawców w jednej kampanii, od najstarszej, wraz z dowodami: odpowiedzią tekstową, linkami do obrazów i wideo, odpowiedziami z szablonu (answers), wierszem danych, nad którym pracowali, a w zadaniach terenowych — ich lokalizacją.

W adresie

Parametr	Opis
`id` wymagany	ID kampanii (id na liście kampanii)

Parametry zapytania

Parametr	Opis
`status`	to_review (pending i resubmitted), pending, resubmitted, revision_requested, approved lub rejected
`since`	Tylko zgłoszenia wysłane w tym czasie lub później, np. 2026-10-01T00:00:00Z
`after_id`	Do stronicowania: tylko zgłoszenia z wyższym id. Użyj next_after_id z poprzedniej strony
`limit`	Ile zwrócić, od 1 do 100 (domyślnie 50)

Aby regularnie pobierać nową pracę, zapamiętuj ostatnie otrzymane id i wysyłaj je następnym razem jako after_id. raw zawiera wszystko, co wysłał wykonawca, na wypadek gdybyś potrzebował czegoś, czego nie ma na liście.

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

Odpowiedź · 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
}

Przykład błędu

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

Oceń zgłoszenie

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

Zatwierdź, odrzuć lub poproś o poprawkę, tak jak przyciskami w panelu. Zatwierdzenie płaci wykonawcy z zarezerwowanych pieniędzy. Odrzucenie zwraca wynagrodzenie i prowizję na twoje saldo i zwalnia miejsce dla innego wykonawcy.

W adresie

Parametr	Opis
`id` wymagany	ID zgłoszenia

Treść JSON

Parametr	Opis
`action` wymagany	approve, reject lub revision
`reason`	Przy reject: powód, który zobaczy wykonawca
`note`	Przy revision (wymagane): co wykonawca ma poprawić

Zgłoszenie możesz ocenić tylko wtedy, gdy czeka na ocenę (pending lub resubmitted). Liczba poprawek jest ograniczona limitem poprawek kampanii; potem możesz tylko zatwierdzić lub odrzucić.

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

Odpowiedź · 200

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

Przykład błędu

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

Sprawdź saldo

GET/api/v1/balance

available to kwota, którą możesz wydać na nowe kampanie, reserved jest zatrzymane dla aktywnych kampanii, a spent to suma dotychczas wypłacona wykonawcom.

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

Odpowiedź · 200

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

Opcje i identyfikatory

GET/api/v1/options

Wymienia kategorie dostępne przez API (needs_url i needs_location pokazują, które wymagają linku lub lokalizacji), dozwolone wartości grupy docelowej i drip feed oraz identyfikatory twoich szablonów, grup wykonawców i testów kwalifikacyjnych.

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

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

Błędy

Campaign API używa kodów statusu HTTP. Gdy coś pójdzie nie tak, success ma wartość false, a error zawiera code do sprawdzenia w kodzie i message do wyświetlenia lub zalogowania. Kontrole kampanii używają tych samych komunikatów co panel.

Status	error.code	Co oznacza
400	`invalid_body, invalid_campaign, invalid_region, category_needs_files, invalid_status, invalid_since, invalid_action, note_required`	Czegoś w żądaniu brakuje lub jest niedozwolone. message mówi, czego.
401	`missing_api_key, invalid_api_key`	Brak klucza API albo klucz jest błędny lub został zastąpiony nowszym.
402	`insufficient_balance`	Dostępne saldo nie pokrywa kampanii. Doładuj saldo i spróbuj ponownie.
403	`test_key_not_allowed, account_suspended`	Użyj produkcyjnego klucza API. Zawieszone konto nie może korzystać z API.
404	`not_found`	Na twoim koncie nie ma kampanii ani zgłoszenia o tym ID.
409	`already_reviewed, review_refused`	Zgłoszenie zostało już ocenione albo ocena nie jest teraz możliwa, np. dlatego, że osiągnięto limit poprawek.
429	`rate_limited`	Ponad 120 żądań na minutę. Odczekaj liczbę sekund podaną w Retry-After.
500	`internal_error`	Problem po naszej stronie. Spróbuj ponownie, a jeśli się powtarza, skontaktuj się z pomocą.

Zewnętrzne testy kwalifikacyjne

Dla testów kwalifikacyjnych działających na twojej stronie.

Przekaż wynik testu Produkcja

GET/api/worker/external_qualification/data

Dla testów kwalifikacyjnych oznaczonych jako zewnętrzne. Wykonawca otwiera twój test z poziomu kwalifikacji i wpisuje swój token wykonawcy na twojej stronie. Gdy skończy, wywołaj ten endpoint z wartością approve lub reject.

Parametr	Opis
`qualification_id` wymagany	ID twojego testu kwalifikacyjnego
`worker_token` wymagany	Token wykonawcy wpisany przez wykonawcę na twojej stronie
`api_token` wymagany	Twój klucz API (klucz testowy dla testowego endpointu)
`decision` wymagany	approve lub reject

Jeśli test płaci premię za zdanie, a saldo zleceniodawcy jej nie pokrywa, zgłoszenie zostaje zapisane jako oczekujące, abyś mógł doładować saldo i zatwierdzić je w panelu.

Wykonawcę można ocenić raz na test. Test musi być aktywny i oznaczony jako zewnętrzny, a klucz API musi należeć do właściciela testu.

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"

Odpowiedź · 200

{
  "success": true
}

Przykład błędu

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

Przetestuj konfigurację

POST/api/worker/external_qualification/data_test

Wyślij te same pola jako JSON na testowy endpoint, używając testowego klucza API. Nic nie jest zapisywane i żaden wykonawca nie jest dotknięty: sprawdzane jest tylko twoje żądanie.

Parametr	Opis
`qualification_id` wymagany	ID twojego testu kwalifikacyjnego
`worker_token` wymagany	Token wykonawcy wpisany przez wykonawcę na twojej stronie
`api_token` wymagany	Twój klucz API (klucz testowy dla testowego endpointu)
`decision` wymagany	approve lub reject

Błędny klucz testowy zwraca status 401; brakujące pola lub błędna decyzja zwracają 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"
  }'

Odpowiedź · 200

{
  "success": true
}

Przykład błędu

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

Błędy wyniku testu

Endpoint wyniku zawsze odpowiada statusem 200. Sprawdź success: gdy ma wartość false, pole error podaje przyczynę:

error	Co oznacza
`Missing required parameters: qualification_id, worker_token, api_token, decision`	Brakuje jednego z czterech parametrów.
`Decision must be 'approve' or 'reject'`	decision ma inną wartość.
`Invalid API token`	Klucz API jest błędny lub został zastąpiony nowszym.
`Worker token not found for this qualification`	Token nie należy do tego testu. Poproś wykonawcę o jego sprawdzenie.
`API token does not belong to the qualification owner`	Użyj klucza konta, które utworzyło test.
`This qualification is not configured for external submissions`	Test nie jest oznaczony jako zewnętrzny.
`This qualification is no longer active`	Test jest wstrzymany lub zakończony.
`This worker has already been evaluated for this qualification`	Każdy wykonawca dostaje jeden wynik na test.
`Worker account is suspended`	Wykonawca nie może teraz zdawać testów.
`No remaining positions for this qualification`	Wszystkie miejsca w teście są zajęte.