{
  "openapi": "3.0.1",
  "info": {
    "title": "Kununu Scraper [Just 💰$1] — Employer Reviews & Ratings (DACH)",
    "description": "💰 $1 per 1,000 records. Scrape kununu.com across DACH — company ratings, employee reviews & salary ranges · score trends · interview outcomes · awards · social handles. Incremental mode tracks new and changed reviews across scheduled runs.",
    "version": "0.2",
    "x-build-id": "Hqdgb8AMvy5mUbpIi"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~kununu-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-kununu-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/blackfalcondata~kununu-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-kununu-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/blackfalcondata~kununu-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-kununu-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "mode": {
            "title": "⚙️ Input mode",
            "enum": [
              "keyword",
              "companyNames",
              "companyUrls",
              "datasetId"
            ],
            "type": "string",
            "description": "Which input to use. 'keyword' paginates search results for a query. 'companyNames' looks up a list of company names. 'companyUrls' uses direct kununu URLs. 'datasetId' reads names from an existing Apify dataset. Leave blank to auto-detect from the fields you fill in. A company that isn't found still returns a result marked NOT_FOUND instead of being skipped."
          },
          "query": {
            "title": "🔍 Search Term(s)",
            "type": "string",
            "description": "Search term for keyword mode (e.g. 'software'). Required when mode=keyword. Leave blank for other modes."
          },
          "companyNames": {
            "title": "Company names",
            "type": "array",
            "description": "List of company names to look up on kununu. Best match from first search page is returned. A name with no match still returns a result marked NOT_FOUND.",
            "items": {
              "type": "string"
            }
          },
          "companyUrls": {
            "title": "Company URLs",
            "type": "array",
            "description": "List of kununu company URLs (e.g. https://www.kununu.com/de/bosch-gruppe). Country code and slug are parsed from each URL — URLs can mix DE/AT/CH. Skips search and matching. Incremental mode works per-slug. A URL with no company on kununu still returns a result marked NOT_FOUND.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "🔗 Start URLs",
            "type": "array",
            "description": "Alias for Company URLs. Paste direct kununu company URLs (e.g. https://www.kununu.com/de/bosch-gruppe). If set, the actor uses URL mode automatically.",
            "items": {
              "type": "string"
            }
          },
          "datasetId": {
            "title": "Dataset ID",
            "type": "string",
            "description": "ID of an existing Apify dataset. Actor reads company names from this dataset and enriches with kununu ratings."
          },
          "companyFieldName": {
            "title": "Company field name",
            "type": "string",
            "description": "Field in the dataset that contains the company name. Default: companyName.",
            "default": "companyName"
          },
          "deduplicateField": {
            "title": "Deduplicate field",
            "type": "string",
            "description": "Optional field to deduplicate by before lookup (e.g. 'companyId'). Useful when multiple jobs share the same company."
          },
          "countryCode": {
            "title": "🌍 Country code",
            "enum": [
              "de",
              "at",
              "ch"
            ],
            "type": "string",
            "description": "Kununu country: de (Germany), at (Austria), ch (Switzerland).",
            "default": "de"
          },
          "industryId": {
            "title": "Industry filter (keyword mode only)",
            "type": "string",
            "description": "Filter results by industry ID. Only applies in keyword search mode. Common IDs: 1=Banking, 2=Construction, 3=Consulting, 4=Education, 5=Publishing, 6=Finance, 7=Healthcare, 8=Insurance, 9=Pharma, 10=IT/Software, 11=Engineering, 12=Automotive, 13=Chemicals, 14=Transport, 15=Retail, 16=Telecom, 17=Energy, 18=Media, 19=Public sector, 20=NGO, 43=Hotels, 44=Gastronomy. Find other IDs by filtering on kununu.com and checking the URL."
          },
          "maxResults": {
            "title": "💯 Max Results",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum number of results to return. 0 = no limit. This is the primary cost control — Apify charges per emitted result event.",
            "default": 100
          },
          "maxPages": {
            "title": "📄 Max pages (keyword mode)",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum number of search result pages to scrape in keyword mode. 0 = no limit. Defensive safety bound — `maxResults` is the primary record cap.",
            "default": 10
          },
          "includeDetails": {
            "title": "📋 Include Full Details",
            "type": "boolean",
            "description": "Fetch the company detail page to extract recommendation rate and website. Doubles the number of requests. Fetches the company profile page (~480 KB per company).",
            "default": false
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Return only the most important fields. Useful for AI-agent workflows.",
            "default": false
          },
          "descriptionFormat": {
            "title": "Description format",
            "enum": [
              "all",
              "text"
            ],
            "type": "string",
            "description": "Pick a single description representation. `all` keeps the description as-is; `text` returns only the plain-text variant.",
            "default": "all"
          },
          "excludeEmptyFields": {
            "title": "Exclude empty fields from output",
            "type": "boolean",
            "description": "Drop null, empty-string, and empty-array fields from each record before push. Smaller payloads for AI agents and dashboards.",
            "default": false
          },
          "incrementalMode": {
            "title": "♻️ Incremental Mode",
            "type": "boolean",
            "description": "Track changes across runs. Emits changeType (NEW/UPDATED/UNCHANGED). NOT_FOUND results are cached for 30 days.",
            "default": false
          },
          "stateKey": {
            "title": "🔑 State Key",
            "type": "string",
            "description": "Unique identifier for the incremental state (e.g. 'dach-companies-v1'). Required when incrementalMode is true."
          },
          "includeReviews": {
            "title": "Include individual reviews",
            "type": "boolean",
            "description": "Also scrape individual employee reviews for each matched company. Requires includeDetails=true. Each review becomes a separate dataset item with type='review'. Fetches the reviews page (~620 KB per company).",
            "default": false
          },
          "maxReviewPages": {
            "title": "Max review pages per company",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum review pages to scrape per company (10 reviews per page). 0 = no limit. Keep this conservative — popular companies can have hundreds of pages.",
            "default": 10
          },
          "reviewSort": {
            "title": "Review sort order",
            "enum": [
              "relevance",
              "newest",
              "oldest",
              "best",
              "worst"
            ],
            "type": "string",
            "description": "Sort order for review scraping. Default is kununu's own default (relevance), which pairs reliably with pagination.",
            "default": "relevance"
          },
          "includeFullSalary": {
            "title": "Include full salary ranges",
            "type": "boolean",
            "description": "Fetch the /gehalt page to get all salary ranges (~20 job titles) instead of the top 3 shown on the detail page. Adds one extra request per company. Requires includeDetails=true. Fetches the salary page (~300 KB per company).",
            "default": false
          },
          "includeCulture": {
            "title": "Include Kulturkompass",
            "type": "boolean",
            "description": "Fetch the /kultur page to extract the Kulturkompass: profile-vs-industry compass score (0-200), MODERN/TRADITIONAL binary classification, 4 culture dimensions (leadership, strategic direction, work-life, working together), strength/weakness/most-voted factors, company statements, and culture-tagged review comments. Adds one extra request per company. Requires includeDetails=true. Returns null for companies with too few culture submissions. Fetches the Kulturkompass page (~280 KB per company).",
            "default": false
          },
          "includeRatingBuckets": {
            "title": "Include rating distribution buckets",
            "type": "boolean",
            "description": "Adds star-rating distribution buckets (excellent 4-5★, good 3-4★, satisfactory 2-3★, subpar 1-2★) with per-bucket review counts and percentages for both employee and applicant reviews. Also enriches output with verification flags (isClaimed, isTopCompanyPaid, hasLocationsContent), employee/candidate review-count splits, and main-office state. Adds 1-2 extra requests per company (one is shared with Include individual reviews when both are enabled). Requires includeDetails=true. Fetches the reviews and applicant pages (~1.2 MB per company) when not already enabled above.",
            "default": false
          },
          "includeContactData": {
            "title": "Include contact data (emails & phones)",
            "type": "boolean",
            "description": "Include extracted email addresses and phone numbers in the output. Disable to comply with stricter PII policies — extractedEmails and extractedPhones will be returned as empty arrays. Company social profiles (LinkedIn, Xing, etc.) are unaffected. Default: enabled.",
            "default": true
          },
          "includeApplicantReviews": {
            "title": "Include applicant (interview) reviews",
            "type": "boolean",
            "description": "Also scrape individual applicant reviews from the /bewerbung feed. Each entry includes interview questions, interview result (hired/rejected/etc.), application year, and applicant-specific rating dimensions (professionalism, responsiveness, predictability, etc.). **Billing**: each emitted applicant review is charged as a 'review-extracted' result, in addition to the extra page requests required to paginate them. A popular employer can have 100+ pages of applicant reviews — cap depth with 'Max applicant review pages' (default 10 pages ≈ 100 reviews per company). Auto-enables includeReviews and includeDetails when set. Fetches the applicant-review page (~555 KB per company).",
            "default": false
          },
          "maxApplicantReviewPages": {
            "title": "Max applicant review pages per company",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum applicant-review pages to paginate per company (10 reviews per page). 0 = no limit. Defaults to 10 — popular employers can have 100+ pages so keep this conservative.",
            "default": 10
          },
          "includeRichContent": {
            "title": "Include rich content (narratives, image/video galleries, job-insight Q&As)",
            "type": "boolean",
            "description": "Adds the richContent block: company slogan, narrative HTML (whatIsSpecial, benefitsStatement, whoWeAre, whoWeAreLookingFor, legalInformation), image gallery, video gallery, and jobInsights Q&A interviews with named employees. This data is HTML-heavy and can multiply output size 5-20× per company. **The HTML is emitted verbatim as the company submitted it to kununu — sanitise/escape on your end before rendering in a browser, an email template, or an LLM prompt.** Requires includeDetails=true. Default: disabled.",
            "default": false
          },
          "includeJobs": {
            "title": "Include open job postings",
            "type": "boolean",
            "description": "Also return the company's open job postings as separate rows (type 'job'): job title, posting date, city and region, employment type, advertised salary when given, the kununu salary benchmark for the role, and a link to the posting. Each job row is billed as a 'Job posting' event. Default: disabled.",
            "default": false
          },
          "maxJobsPerCompany": {
            "title": "Max job postings per company",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum job postings returned per company when 'Include open job postings' is on. 0 = all open postings. Default: 30.",
            "default": 30
          },
          "fetchJobDetails": {
            "title": "Fetch full job details",
            "type": "boolean",
            "description": "Enrich every job row with the full posting: description (text, HTML and Markdown), description sections (requirements, responsibilities, application process), benefits, full address, remote options, application link and closing date. One extra page per job. Auto-enables 'Include open job postings'. Default: disabled.",
            "default": false
          },
          "enrichEmails": {
            "title": "Find emails on the company website",
            "type": "boolean",
            "description": "Visit the employer's own website (homepage and contact page) and add the email addresses published there to the company row as websiteEmails, plus the best general contact address as contactEmail. Auto-enables includeDetails. Billed as one 'Website contact email' event per company where at least one address is found. Default: disabled.",
            "default": false
          },
          "telegramToken": {
            "title": "🔑 Telegram Bot Token",
            "type": "string",
            "description": "Telegram bot token (from @BotFather). Required for Telegram notifications."
          },
          "telegramChatId": {
            "title": "💬 Telegram Chat ID",
            "type": "string",
            "description": "Telegram chat or channel ID (e.g. \"-100123456789\"). Required when telegramToken is set."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord incoming webhook URL. Server Settings → Integrations → Webhooks → New Webhook."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL. api.slack.com/messaging/webhooks."
          },
          "whatsappAccessToken": {
            "title": "📱 WhatsApp Access Token",
            "type": "string",
            "description": "WhatsApp Cloud API permanent access token (System User token from Meta Business). Recipient must have messaged the business number within the last 24h (service-conversation window — free since Nov 2024)."
          },
          "whatsappPhoneNumberId": {
            "title": "📞 WhatsApp Phone Number ID",
            "type": "string",
            "description": "Your WhatsApp Business phone-number ID (numeric, from Meta dashboard). Required when whatsappAccessToken is set."
          },
          "whatsappTo": {
            "title": "📲 WhatsApp Recipient",
            "type": "string",
            "description": "Recipient phone in E.164 format without + (e.g. \"436641234567\"). Recipient must have messaged your business number within last 24h."
          },
          "webhookUrl": {
            "title": "🪝 Generic Webhook URL",
            "type": "string",
            "description": "Receives a JSON POST with {metadata, items} after each run. Universal escape hatch for n8n / Make / Zapier / custom backends."
          },
          "webhookHeaders": {
            "title": "📋 Webhook Headers",
            "type": "object",
            "description": "Optional JSON object of custom headers (e.g. {\"Authorization\":\"Bearer ...\"})."
          },
          "notificationLimit": {
            "title": "📊 Max Items Per Notification",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of items included in each notification message (1–20).",
            "default": 5
          },
          "notifyOnlyChanges": {
            "title": "🔄 Notify Only New/Updated",
            "type": "boolean",
            "description": "When Incremental Mode is on, only send notifications for NEW and UPDATED items. Has no effect outside incremental mode.",
            "default": false
          },
          "appConnector": {
            "title": "Send results to Notion (or another connected app)",
            "type": "string",
            "description": "Optional. Pick a connected app under Settings → API & Integrations to receive your results. Notion is supported today (a run-summary page); other MCP connectors are best-effort as Apify expands its catalog."
          },
          "mcpIssueTeam": {
            "title": "Issue tracker team",
            "type": "string",
            "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one."
          },
          "emitUnchanged": {
            "title": "🔄 Emit Unchanged Listings",
            "type": "boolean",
            "description": "When incremental mode is on, also emit listings whose content has not changed since the last run.",
            "default": false
          },
          "emitExpired": {
            "title": "⚰️ Emit Expired Listings",
            "type": "boolean",
            "description": "When incremental mode is on, also emit listings that were seen before but are no longer found.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}