Element External Integration API — dokumentacja

8.1 — Health check

Kontrola łączności bez uwierzytelniania.

{ "status": "ok", "apiVersion": "v1-beta" }

8.2 — Lista projektów

Stronicowana lista aktywnych projektów.

{ "data": [
    { "id": "ff315ea1-…", "name": "Senior PHP Developer",
      "positionName": null, "isRemote": true,
      "statusId": "73f09ef2-…", "createdAt": "2021-10-31T11:42:24+00:00" } ],
  "meta": { "page": 1, "perPage": 20, "total": 8 } }

Błędy: 401, 429.

8.3 — Szczegóły projektu

Pełne dane projektu wraz z listą etapów. Pola responsibilities, requirements, offer zawierają treść HTML. minimumSalary/maximumSalary w walucie tenanta (0 = nieustawione).

{ "data": { "id": "ff315ea1-…", "name": "Senior PHP Developer",
    "minimumSalary": 12000, "maximumSalary": 18000, "numberOfVacancies": 4,
    "stages": [
      { "id": "…", "name": "Aplikacja", "isApplicationType": true },
      { "id": "…", "name": "Rozmowa", "isApplicationType": false } ] } }

Błędy: 401, 404 project_not_found, 429.

8.4 — Etapy projektu

Sama tablica etapów (kształt jak data.stages z 8.3). Etap o isApplicationType: true to etap aplikacyjny (max jeden na projekt).

Błędy: 401, 404 project_not_found, 429.

8.5 — Kandydaci w projekcie

Stronicowana lista kandydatów; opcjonalny filtr stageId. Pola: id, firstName, lastName, email, stageId, isRejected, addedAt. Pole email może być puste — od v1.3 aplikację przez API można złożyć bez adresu e-mail (zob. 8.11).

Błędy: 401, 404 project_not_found, 429.

8.6 — Schemat formularza aplikacyjnego ZMIANA v1.2

Zwraca pełną strukturę formularza (metadane + zagnieżdżone sekcje → pytania → warianty odpowiedzi). Użyj do zbudowania mapy odpowiedzi i pobrania version do POST /apply.

{ "data": {
    "id": "78132d76-…", "projectId": "ff315ea1-…", "schemaId": "d6aea4da-…",
    "formType": "custom", "schemaType": "default",
    "schemaName": { "pl": "Formularz aplikacyjny" },
    "version": "2026-04-09T12:55:57+00:00",
    "isEmailRequired": true, "isPhoneNumberRequired": true, "isCvRequired": true,
    "sections": [
      { "id": "1f0d3c8a-…", "name": { "pl": "Dane podstawowe" }, "order": 0,
        "questions": [
          { "id": "9a2c7e44-…", "type": "oneAnswer", "subtype": null,
            "label": { "pl": "Forma zatrudnienia" }, "isRequired": true, "order": 0,
            "answers": [
              { "id": "b7e1d2a3-…", "content": { "pl": "Umowa o pracę" },
                "isDisqualifying": false, "order": 0 } ] } ],
        "subFormIds": ["30c5a856-…"],
        "subForms": [                          // ◆ v1.2: rozwinięte
          { "id": "30c5a856-…", "type": "week-days",
            "name": { "pl": "W jakich dniach możesz się spotkać?" },
            "sections": [
              { "id": "c1c4ae4c-…", "name": { "pl": "pn." }, "order": 0,
                "questions": [
                  { "id": "4a793138-…", "type": "yesNo", "subtype": "weekDay",
                    "label": { "pl": "pn." }, "isRequired": false, "order": 0 },
                  { "id": "499a4fed-…", "type": "oneAnswer", "subtype": "hourFrom",
                    "label": { "pl": "Od godziny" } } ],
                "subFormIds": [], "subForms": [] } ] } ] } ] } }

Pola sekcji: id, name, description, payload, order, questions[], subFormIds[], subForms[].

Obiekt podformularza (subForms[]): id (zgodny z pozycją w subFormIds sekcji-rodzica), type (np. calendar-days, week-days), name (mapa lokalizacji), sections[] (ta sama struktura co sekcje najwyższego poziomu — rekurencyjnie z questions, subFormIds, subForms).

Obiekt pytania: id (klucz w mapie answers dla POST /apply), type (oneAnswer, multiAnswers, scale, yesNo, open, financialRequirements, languages, file, referral, …), subtype (np. calendarDay, weekDay, hourFrom, hourTo), label, isRequired, order, answers[] (warianty: id — wartość dla oneAnswer/multiAnswers — content, isDisqualifying, order).

Błędy: 401, 404 project_not_found, 404 application_form_not_found, 429.

8.7 — Wypełniony formularz kandydata

Zwraca wypełniony formularz danego kandydata — sekcje z pytaniami i przesłanymi odpowiedziami.

{ "data": { "projectId": "ff315ea1-…", "candidateId": "87c42b09-…",
    "applicationFormId": "78132d76-…", "submittedAt": "2026-05-27T17:57:48+00:00",
    "formVersion": "2026-04-09T12:55:57+00:00", "locale": "pl",
    "sections": [
      { "title": "Pytania aplikacyjne", "items": [
        { "questionId": "ae8a8a8a-…", "label": "Ocena PHP",
          "type": "scale", "subtype": null, "answer": "1" } ] } ] } }

items[].answer zależy od type (string | int | bool | tablica | null = brak odpowiedzi). Wewnętrzny scoring (obtainedScore, isDisqualified) oraz pytania plikowe są celowo pominięte.

Błędy: 401, 404 project_not_found, 404 application_form_not_found, 429.

8.8 — Profil kandydata

Pełny profil (kontakt, doświadczenie, edukacja, umiejętności, języki, certyfikaty). Pola m.in. experience[], education[], skills[], languageSkills[] (cefrLevel A1–C2), certifications[]. Wewnętrzny description CRM jest wykluczony.

Błędy: 401, 404 candidate_not_found, 429.

8.9 — Projekty kandydata

Stronicowana lista aktywnych projektów, w których uczestniczy kandydat (malejąco po dacie dodania).

Błędy: 401, 404 candidate_not_found, 429.

8.10 — Publiczne notatki kandydata

Stronicowana lista publicznych notatek. Notatki prywatne nigdy nie są ujawniane. Opcjonalny projectId zawęża do kontekstu projektu. Pola: id, content, createdAt, createdBy, projectId (lub null).

Błędy: 401, 404 candidate_not_found, 429.

8.11 — Aplikacja (utworzenie kandydata) ZMIANA v1.3

Tworzy nowego kandydata i dodaje go do projektu na etapie aplikacyjnym.

Content-Type: multipart/form-data (z plikami) lub application/x-www-form-urlencoded (bez plików).

Mapowanie wartości answers wg typu pytania:

Odpowiedź 201:

{ "candidateId": "4b257ea8-…", "projectId": "ff315ea1-…",
  "answerSheetId": "3c9b1f7e-…" }   // answerSheetId tylko gdy podano poprawne answers; inaczej null

Przykład (kontakt + CV + załączniki + odpowiedzi):

curl --user "api+voicebot@acme.local:<hasło>" \
  -F "firstName=Anna" -F "lastName=Nowak" -F "email=anna.nowak@example.com" \
  -F "source=voicebot-inbound" \
  -F "cv=@./cv.pdf" \
  -F "attachments[]=@./portfolio.pdf" -F "attachments[]=@./certyfikat.png" \
  -F 'version=2026-04-09T12:55:57+00:00' \
  -F 'answers={"9a2c7e44-…":"b7e1d2a3-…","cal-day-q-id":"2026-06-30"}' \
  https://acme.elementapp.ai/api/v1-beta/projects/ff315ea1-…/apply

Przykład minimalny (bez e-maila, od v1.3):

curl --user "api+voicebot@acme.local:<hasło>" \
  -F "firstName=Anna" -F "lastName=Nowak" -F "phoneNumber=+48 500 100 200" \
  https://acme.elementapp.ai/api/v1-beta/projects/ff315ea1-…/apply

Błędy: 400 validation_failed, 400 invalid_answers, 401, 404 project_not_found, 409 no_application_stage, 409 stale_form_version, 429.

8.12 — Dodanie notatki do kandydata

Dodaje publiczną notatkę (autor: konto API, w UI jako API: <nazwa-systemu>). Content-Type: application/x-www-form-urlencoded. Pola: content (wymagane, do 10 000 znaków), projectId (opcjonalne). Odpowiedź 201: { "noteId": "…" }.

Błędy: 400 validation_failed, 401, 404 candidate_not_found, 429.