{"openapi":"3.0.0","paths":{"/health/ping":{"get":{"operationId":"HealthController_ping","parameters":[],"responses":{"200":{"description":""}},"tags":["Health"]}},"/v1/status":{"get":{"operationId":"StatusController_status","parameters":[],"responses":{"200":{"description":""}},"summary":"API version and endpoint discovery","tags":["system"]}},"/v1/job-application":{"post":{"description":"Creates a job application and queues talent/match upsert processing.\nSend as `multipart/form-data`. Up to 5 files, 10 MB each.\n\n**This endpoint must be called from your backend server — never from browser-side code.**\n\nYour channel API key must stay secret on your server. A typical integration:\n\n1. Candidate fills in your application form on the frontend.\n2. Your frontend submits the form to **your own backend endpoint**.\n3. Your backend validates the data, applies a CAPTCHA or similar bot/spam challenge,\n   then forwards the application to `POST /v1/job-application` with the channel API key.\n\n**Bot & spam protection is your responsibility** on the frontend→backend leg.\nTaloo receives data from your server and trusts it. Implement a CAPTCHA (e.g. Turnstile,\nhCaptcha, reCAPTCHA) or honeypot on your own form endpoint before forwarding here.","operationId":"JobApplicationController_submit","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/JobApplicationDto"}}}},"responses":{"201":{"description":""}},"summary":"Submit a job application with optional file attachments","tags":["job-applications"]}},"/v1/track-action":{"post":{"description":"Records a vacancy view or application-form-open event in the Taloo analytics store.\n\n**This endpoint must be called from your backend server — never from browser-side code.**\n\nYour channel API key must be kept secret on your server. A typical integration looks like this:\n\n1. User opens a vacancy page on your platform.\n2. Your frontend page notifies your backend (e.g. via a first-party endpoint or event queue).\n3. Your backend calls `POST /v1/track-action` with the channel API key in the header.\n4. Forward the user's real `webOrigin` (full browser URL **with all UTM params intact**) and their `userAgent` header.\n\n**UTM attribution — this is important:**\nIf the user arrived on your platform via an external job board (e.g. jobs.ch, LinkedIn), their browser URL\nwill already contain `utm_source`, `utm_medium`, etc. added by that referrer.\nForward this URL as-is in `webOrigin` — those params are the primary attribution signal and tell Taloo\nwhich external platform generated the traffic. Do not strip or replace UTM params.\n\nIf the user navigated directly to your platform (no UTM params), Taloo attributes the event to your\nplatform automatically via hostname detection. Forwarding the URL is still recommended.\n\n**Bot protection:** Forward the end-user's `User-Agent` in the `userAgent` body field.\nTaloo applies bot detection on that value. You should additionally protect your own\nfrontend→backend exchange with a CAPTCHA or similar challenge to prevent fabricated events\nfrom reaching this endpoint.","operationId":"TrackActionController_track","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackActionDto"}}}},"responses":{"200":{"description":""}},"security":[{"ChannelApiKey":[]}],"summary":"Track a vacancy interaction","tags":["track-action"]}}},"info":{"title":"Taloo Public API","description":"Public-facing REST API for external consumers","version":"1.0","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"ChannelApiKey":{"type":"apiKey","in":"header","name":"x-channel-api-key"}},"schemas":{"JobApplicationDto":{"type":"object","properties":{"firstName":{"type":"string","example":"Anna"},"lastName":{"type":"string","example":"Muster"},"sex":{"type":"string","enum":["MALE","FEMALE","OTHER"],"example":"FEMALE"},"email":{"type":"string","example":"anna.muster@example.com"},"phone":{"type":"string","example":"+41 79 123 45 67"},"language":{"type":"string","enum":["DE","EN","FR","IT"],"example":"DE","description":"Preferred language of the applicant. Defaults to DE."},"vacancyPublicUuid":{"type":"string","example":"b2f3c1d4-...","description":"UUID of the vacancy. Omit for spontaneous applications."},"tenantBranchUuid":{"type":"string","example":"tenant-branch-uuid-123","description":"Optional branch UUID for spontaneous applications. Ignored when vacancyPublicUuid is provided."},"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"Up to 5 files, 10 MB each (CV, cover letter, …)"}},"required":["firstName","lastName","sex","email"]},"TrackActionDto":{"type":"object","properties":{"action":{"type":"string","enum":["VACANCY_VIEWED","VACANCY_APPLICATION_FORM_OPENED"],"description":"The type of interaction to record"},"vacancyPublicUuid":{"type":"string","description":"The public UUID of the vacancy this action relates to","example":"abc-123"},"webOrigin":{"type":"string","description":"Full URL of the page the end-user is currently viewing, **including any UTM query parameters**. Forward the actual browser URL — not your backend server URL.\n\n**Referral traffic (user arrived from an external job board):** The browser URL will already contain the referrer's UTM params (e.g. `?utm_source=jobs.ch`). Forward this URL as-is — these params identify the real traffic origin and are the primary attribution signal.\n\n**Own/direct traffic (user navigated directly to your platform):** No UTM params will be present. Taloo will attribute the event to your platform automatically using hostname detection, so forwarding the URL is still useful but the source will be your platform.","example":"https://platform.example.com/jobs/abc-123?utm_source=jobs.ch&utm_medium=organic"},"userAgent":{"type":"string","description":"User-Agent string of the end-user's browser. Forward the incoming request's User-Agent header from your frontend. Used to filter out known bots and crawlers.","example":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"}},"required":["action","vacancyPublicUuid"]}}}}