{
  "openapi": "3.0.1",
  "info": {
    "title": "Hays Jobs Scraper - 9 Countries",
    "description": "Scrape hays.com — global recruitment leader across 9 markets (DE, AT, CH, GB, FR, NL, BE, DK, AU). Salary data, geo coordinates, structured job descriptions, employment types, and specialist categories. Incremental mode detects new and changed listings.",
    "version": "0.1",
    "x-build-id": "Uf9MkKGk5rLYNfWjC"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~hays-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-hays-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~hays-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-hays-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~hays-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-hays-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": {
          "query": {
            "title": "🔍 Search Term(s)",
            "type": "string",
            "description": "Job search keywords. Use JSON array for multi-query."
          },
          "country": {
            "title": "🌍 Country",
            "enum": [
              "DE",
              "AT",
              "CH",
              "GB",
              "FR",
              "AU",
              "NL",
              "BE",
              "DK"
            ],
            "type": "string",
            "description": "Hays country portal to search.",
            "default": "DE"
          },
          "location": {
            "title": "📍 Location",
            "type": "string",
            "description": "City, state, or region. Use JSON array for multi-location."
          },
          "startUrls": {
            "title": "🔗 Start URLs",
            "type": "array",
            "description": "Direct search or job detail URLs.",
            "items": {
              "type": "string"
            }
          },
          "maxResults": {
            "title": "💯 Max Results",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Hard cap on total job listings emitted to your dataset (0 = unlimited). This is the primary cost control — Apify charges per emitted record, so use this to bound your run cost regardless of how many listings the source has. If both maxResults and maxPages are set, the LOWER cap wins. Memory scales automatically: ≤25 → 256 MB, ≤200 → 512 MB, 201+ → 1024 MB.",
            "default": 25
          },
          "maxPages": {
            "title": "Max Pages",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Defensive cap on the number of SERP pages crawled per search source. Used to protect against runaway pagination. In normal operation, maxResults controls the run size — set maxPages only when you suspect the source returns more pages than expected. If both are set, the LOWER cap wins.",
            "default": 5
          },
          "includeDetails": {
            "title": "📋 Include Full Details",
            "type": "boolean",
            "description": "Fetch each job's detail page for full description, salary data, and company info.",
            "default": true
          },
          "includeCompanyProfile": {
            "title": "🏢 Include Company Profile",
            "type": "boolean",
            "description": "Fetch company overview pages for industry, headcount, and more.",
            "default": false
          },
          "descriptionMaxLength": {
            "title": "✂️ Description Max Length",
            "minimum": 0,
            "type": "integer",
            "description": "Truncate description to this many characters. 0 = no truncation.",
            "default": 0
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Output only core fields (for AI-agent/MCP workflows).",
            "default": false
          },
          "incrementalMode": {
            "title": "♻️ Incremental Mode",
            "type": "boolean",
            "description": "Compare against previous run state. Requires stateKey.",
            "default": false
          },
          "stateKey": {
            "title": "🔑 State Key",
            "type": "string",
            "description": "Optional stable identifier for the tracked search universe. Leave empty to auto-derive a stable identifier from your search inputs — different keyword/location/filter combinations get isolated state automatically."
          },
          "emitUnchanged": {
            "title": "Emit Unchanged Records",
            "type": "boolean",
            "description": "When incremental, also emit records that haven't changed.",
            "default": false
          },
          "emitExpired": {
            "title": "Emit Expired Records",
            "type": "boolean",
            "description": "When incremental, also emit records no longer found.",
            "default": false
          },
          "skipReposts": {
            "title": "🚫 Skip Reposts",
            "type": "boolean",
            "description": "When incremental, skip jobs that are reposts of previously seen (now expired) jobs.",
            "default": false
          },
          "telegramToken": {
            "title": "📱 Telegram Bot Token",
            "type": "string",
            "description": "Telegram bot token from @BotFather. Pairs with Telegram Chat ID. Pair with Incremental Mode for real-time alerts on new/updated items only."
          },
          "telegramChatId": {
            "title": "💬 Telegram Chat / Channel ID",
            "type": "string",
            "description": "Chat ID (from @userinfobot) or channel ID (starts with -100 for channels). Required when Telegram Bot Token is set."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Incoming Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL (Slack App → Incoming Webhooks → Add New Webhook). Formats jobs as Slack blocks."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord channel webhook URL (Server Settings → Integrations → Webhooks → New Webhook). Sends rich embeds colour-coded by change type (green=NEW, amber=UPDATED)."
          },
          "whatsappAccessToken": {
            "title": "📲 WhatsApp Access Token",
            "type": "string",
            "description": "WhatsApp Cloud API permanent System User token from Meta Business. Pairs with WhatsApp Phone Number ID and recipient phone."
          },
          "whatsappPhoneNumberId": {
            "title": "📞 WhatsApp Phone Number ID",
            "type": "string",
            "description": "Numeric WhatsApp Business phone-number ID from Meta dashboard."
          },
          "whatsappTo": {
            "title": "📨 WhatsApp Recipient (E.164)",
            "type": "string",
            "description": "Recipient phone in E.164 format (e.g. \"15551234567\"). Recipient must have messaged the business number within the last 24h, otherwise Meta rejects free-form text."
          },
          "webhookUrl": {
            "title": "🔗 Generic Webhook URL",
            "type": "string",
            "description": "POSTs a JSON payload `{metadata, items}` to your endpoint. Universal hook for n8n / Make / Zapier / custom backends."
          },
          "webhookHeaders": {
            "title": "📑 Webhook Headers (JSON)",
            "type": "object",
            "description": "Optional headers (e.g. `{\"Authorization\": \"Bearer ...\"}`) sent with the webhook POST."
          },
          "notificationLimit": {
            "title": "🔢 Notification Limit",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of jobs included per notification batch (1–20). Prevents spam on large result sets.",
            "default": 5
          },
          "notifyOnlyChanges": {
            "title": "🆕 Notify Only on Changes",
            "type": "boolean",
            "description": "When ON together with Incremental Mode, send notifications only for NEW and UPDATED jobs. Has no effect outside incremental mode.",
            "default": false
          },
          "includeRunMetadata": {
            "title": "📣 Include Run Summary in Notifications",
            "type": "boolean",
            "description": "Prepend a one-line summary (search label + total count) to each notification batch.",
            "default": true
          },
          "descriptionFormat": {
            "title": "Description format",
            "enum": [
              "all",
              "text",
              "html",
              "markdown"
            ],
            "type": "string",
            "description": "Pick a single description representation. `all` keeps every variant; `text` / `html` / `markdown` drop the others.",
            "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
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}