Dla pracodawców

API integracji dla firm

Twój ATS albo strona kariery publikuje, zmienia i zamyka oferty u nas automatycznie - bez logowania i przepisywania. Dostępne na każdym planie, także bezpłatnym.

Utwórz klucz API w panelu Dokumentacja

Jak zacząć

Utwórz klucz API w panelu firmy

Klucz zobaczysz raz - zapisz go w konfiguracji systemu, nie w kodzie strony ani w adresie URL. Do testów na serwerze testowym służą klucze sp_test_.

Sprawdź, czy klucz działa

curl https://api.szukaniepracy.pl/api/integrations/v1/me \
  -H "Authorization: Bearer sp_live_..."

Wyślij ofertę z identyfikatorem ze swojego systemu

Ten sam identyfikator to zawsze ta sama oferta - można bezpiecznie ponawiać, a wysłanie tej samej treści niczego nie zmienia.

curl -X PUT https://api.szukaniepracy.pl/api/integrations/v1/jobs/external/TRF-2026-0142 \
  -H "Authorization: Bearer sp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Magazynier - zmiana dzienna",
    "responsibilities": ["Kompletacja zamówień", "Obsługa skanera"],
    "requirements": ["Uprawnienia UDT na wózek widłowy"],
    "industries": ["logistics"],
    "workModes": ["office"],
    "workSchedules": ["full_time"],
    "locations": [{ "city": "Poznań" }],
    "salaries": [
      { "contractType": "uop", "from": 5200, "to": 6100, "currency": "PLN", "timeUnit": "monthly", "kind": "gross" }
    ]
  }'

Zasady

Autoryzacja. Każde wywołanie wysyła klucz API w headerze Authorization: Bearer sp_live_…. Klucz tworzysz w panelu firmy i widzisz go tylko raz - trzymaj go w konfiguracji serwera, nigdy w kodzie strony, aplikacji mobilnej ani w adresie URL. Klucze sp_test_… działają wyłącznie na serwerze testowym, produkcja je odrzuca.

Dwa sposoby wskazania oferty. Każda oferta firmy ma nasz identyfikator id. Oferta wysłana z Twojego systemu ma też Twój identyfikator externalId.

/jobs/external/{externalId} - dla integracji z ATS. PUT tworzy ofertę albo ją aktualizuje, więc możesz go bezpiecznie ponawiać: ten sam externalId to zawsze ta sama oferta, a wysłanie tej samej treści niczego nie zmienia. Nowe oferty powstają tylko tędy.
/jobs/internal/{id} - dla ofert, których nie ma w Twoim systemie, np. dodanych ręcznie w panelu. PUT tylko aktualizuje.
GET /jobs - wszystkie oferty firmy z oboma identyfikatorami. Stąd weźmiesz id oferty dodanej w panelu.

Aplikacje. Kandydaci, którzy aplikowali na Twoje oferty, z danymi kontaktowymi i etapem rekrutacji (applications:read). Nie wysyłamy webhooków - odpytuj cyklicznie GET /applications?updatedSince=… z chwilą poprzedniego odczytu, a dostaniesz nowe aplikacje i te, którym zmienił się etap. Etap zmieniasz przez PATCH /applications/{id} (applications:write): new, contact, interview, hired, rejected - te same etapy co w panelu firmy, obowiązuje ostatni zapis.

Zmiany z kilku miejsc. Ofertę można edytować przez API i w panelu firmy - obowiązuje ostatni zapis. Poprawka wprowadzona w panelu albo przez /internal zostaje do następnej wysyłki z Twojego systemu pod /external. Wyjątek: oferta wstrzymana w panelu pozostaje wstrzymana, dopóki ktoś nie wznowi jej w panelu - status: active w PUT jej nie wznawia.

Błędy. Każda odpowiedź z błędem ma ten sam kształt: { "code": "…", "message": "…", "errors": [{ "field", "code" }] }. Obsługę opieraj na code - message jest dla człowieka i może się zmienić. Przy błędach walidacji lista errors wskazuje każde błędne pole.

Limity. 120 wywołań na minutę na klucz i 600 na firmę. Każda odpowiedź podaje stan limitu w headerach RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset. Po przekroczeniu dostaniesz 429 - ponów wywołanie po liczbie sekund z headera Retry-After.

Wersjonowanie. W v1 tylko dodajemy: nowe pola, endpointy i wartości słowników - napisz integrację tak, żeby je pomijała. Nieznane pola w request body nie powodują błędu, wracają w warnings, więc możesz wysyłać pola, które obsłużymy później. Zmiana łamiąca zgodność to nowa wersja v2, a v1 działa jeszcze co najmniej 12 miesięcy od ogłoszenia jej wycofania.