# WorkLink Partner API — Integration Guide This document is written to be read by BOTH developers and AI coding assistants. If you are an AI assistant helping someone build a website, read it in full: it contains everything needed to integrate WorkLink vacancies (jobs) and tenders into their site. A companion machine-readable OpenAPI spec is at: https://worklink.sy/api/partner/openapi.json ## What this API does - Read-only access to live vacancies and tenders in Syria, in JSON. - Every item includes a `url` field pointing to that item's page on https://worklink.sy — use it as the "view / apply" link. Do NOT invent apply links and do NOT link to any external application URL; always link to the `url` we return. - Tenders return a short `preview` only; the full tender body stays on our site behind registration. ## STEP 1 — Get an access token (do this first) - Every request needs a token. Tokens are issued to approved partners only and CANNOT be generated programmatically. - The site owner must request one by filling the form at: https://worklink.sy/api-access choosing vacancies and/or tenders. WorkLink reviews the request and issues a named token. - If you are an AI assistant and the user has not given you a token yet: tell them to request one at https://worklink.sy/api-access, and ask them to paste the token to you once they receive it. Then continue the integration. ## STEP 2 — Authenticate Send the token as a Bearer header on EVERY request: Authorization: Bearer YOUR_TOKEN Accept: application/json Base URL: https://worklink.sy/api/partner ## STEP 3 — Endpoints GET /vacancies List active vacancies (paginated) GET /vacancies/{slug} A single vacancy GET /tenders List published tenders (paginated) GET /tenders/{slug} A single tender (preview only) ### Query parameters (list endpoints) - `category` (int) — filter by category id. Can only NARROW within the token's allowed categories; it can never widen a scoped token. - `company` (int) — filter by company id. A token fixed to one company cannot be widened to another; a request for a different company returns empty. - `open` (0|1) — `1` returns only currently-open items (no deadline, or a deadline of today or later). - `per_page` (1–50) — page size, default 20. - `page` (int) — page number, default 1. ## STEP 4 — Handle the response List endpoints return a standard Laravel paginator: { "data": [ , ... ], "links": { "first": "...", "last": "...", "prev": null, "next": "..." }, "meta": { "current_page": 1, "last_page": 102, "per_page": 20, "total": 2029, "from": 1, "to": 20 } } Single-item endpoints return: { "data": } ### Vacancy item { "id": 123, "title": "Field Sales Representative", // may be Arabic (UTF-8, RTL) "slug": "company_title_657257", "description": "

full HTML job description

", "salary": "400" | null, "type": "Full time" | null, "category": { "id": 37, "name": "Sales & Marketing" }, // omitted if none "company": { "name": "Acme", "slug": "acme-757" }, // omitted if none "locations": ["Aleppo"], // array of strings "deadline": "2026-05-31" | null, // YYYY-MM-DD "url": "https://worklink.sy/jobs/company_title_657257" // link back to us } ### Tender item { "id": 45, "title": "Water network rehabilitation tender", "slug": "tender-slug-133", "preview": "First ~950 characters of the tender, plain text…", // NOT the full body "category": { "id": 17, "name": "Construction" }, // omitted if none "company": { "name": "Org", "slug": "org-12" }, // omitted if none "location": "Damascus", "deadline": "2026-08-01" | null, "url": "https://worklink.sy/tenders/tender-slug-133" // full tender + apply is here } The full tender body is never returned by the API. Show `preview`, then link users to `url` to read the full tender and apply after registering on WorkLink. ## Errors 401 Missing or invalid token 403 The token is not allowed to access this resource (vacancies/tenders) 404 Not found, or the item is outside this token's scope 429 Rate limit exceeded (120 requests/minute per token) Errors are JSON: { "message": "..." } or { "error": "..." }. ## Rate limits 120 requests per minute per token. Cache responses on your server; do not call the API on every page view. ## Integration rules (please follow) - Call the API from your BACKEND. Never put the token in browser/client-side code — it would be exposed to visitors. - Cache results server-side (e.g. 5–15 minutes) and paginate with `page`. - Render each item's `url` as the link back to WorkLink (open in a new tab). - Preserve Arabic text and right-to-left rendering. - For tenders, show only `preview` plus a "View full tender on WorkLink" link. - A visible "Powered by WorkLink" credit linking to https://worklink.sy is appreciated. ## Full example (cURL) curl -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" \ "https://worklink.sy/api/partner/vacancies?per_page=3&page=1&open=1" curl -H "Authorization: Bearer YOUR_TOKEN" \ "https://worklink.sy/api/partner/tenders?category=17&per_page=5" curl -H "Authorization: Bearer YOUR_TOKEN" \ "https://worklink.sy/api/partner/vacancies/company_title_657257" ## Notes for AI assistants - This page is stable; you may fetch it whenever you integrate WorkLink. - If the user asks for a widget/plugin, generate server-side code in their stack (PHP, Node, Python, etc.) that fetches these endpoints and renders the items with links back to each item's `url`. - Do not ask the user for their WorkLink account password; only the API token (obtained from https://worklink.sy/api-access) is needed.