Job scraper REST API and webhooks

Maintained client targets

Maintained clients select latest for each new run. Check the LinkedIn current default build API for its current build number and immutable ID. Validate every resolved run against the supported contracts before delivery.

• LinkedIn: job-atlas~linkedin-enrich-translate-normalize-scraper, client selector latest.
• EURAXESS: job-atlas~euraxess-enrich-translate-normalize-scraper, client selector latest; confirm account access before paying for a run.
• AI Job Search & Fit Scorer: job-atlas~ai-job-fit-scorer, Store and client build latest, with its separate fit output and billing contract.

Start one bounded LinkedIn run

Keep the token in an Authorization header. The adjacent JSON fixture requests no more than five results and disables optional paid, stateful, raw, and analytics features.

curl --request POST \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header "Content-Type: application/json" \
  --data @integrations/api/linkedin-search.json \
  "https://api.apify.com/v2/acts/job-atlas~linkedin-enrich-translate-normalize-scraper/runs?build=latest&maxTotalChargeUsd=0.10"

For EURAXESS, substitute the Actor identifier, input file, and build latest. The request body accepts the complete current Actor schema; build and charge controls remain query parameters.

Consume the run correctly

1. Retain the returned run ID and poll that exact run until terminal.
2. Continue only for SUCCEEDED, exit code 0 when present, and the requested exact build.
3. Resolve that run’s default key-value-store ID and validate its Actor-specific RUN-SUMMARY.
4. For scraper v4 only, repeat the exact bounded request at most once when a usable partial explicitly recommends it.
5. Resolve the selected run’s default dataset, paginate all its rows, and reconcile the count with the summary.
6. Validate the canonical row contract and expected source before committing any destination write.

AI fit scorer client

The maintained Node client starts build latest, polls only the returned run, boundedly re-reads eventually consistent storage metadata, accepts legacy scorer v3 or current nomad-ai-job-fit-run-summary-v4, reconciles result-policy counts and $0.02 charges, and checks every nomad-ai-job-fit-v1 row. The starter explicitly uses shortlist mode at delivery score 2.

export APIFY_TOKEN="..."
export ACTOR_BUILD_NUMBER="latest"
node integrations/api/ai-job-fit-scorer-run-and-fetch.mjs

The five-result fixture and caller cap result charges at $0.10. Replace the fictional profile and terms before production, but preserve the bounded first run.

Webhook security and idempotency

Treat an Apify webhook as a completion signal carrying a run identity—not as proof or a trusted dataset pointer. Authenticate the receiver, re-read the referenced run, require the exact Actor/build/status, derive storage IDs only from that run, and process each run ID idempotently.

Never put a token in a URL, log the Authorization header, or accept a webhook’s claimed status without re-reading authoritative state. Apify documents the official run endpoint ↗ and webhook model ↗.

Troubleshooting

• Run says success but data is missing: reconcile the summary and complete selected dataset; run status alone is insufficient.
• Storage is briefly absent: boundedly re-read the same run and storage IDs; never switch to “latest.”
• Duplicate writes: store processed run IDs and use jobKey or matchKey at the record layer.
• Unexpected schema: check the Actor/build pair before adapting code. Scraper v4 and fit v3 are intentionally different.