Skip to content

getting-started.md

Latest commit

 

History

History
94 lines (53 loc) · 6.09 KB

getting-started.md

File metadata and controls

94 lines (53 loc) · 6.09 KB
Raw

Getting started

Reqbeat watches company career pages and job boards across hundreds of sources and turns them into hiring signals you can query. Every fact is detected on a real source and carries the date we first saw it. Nothing is inferred. The corpus rebuilds every 3 hours.

This page takes you from a key to your first signal in about five minutes, then shows the calls most people build on.

1. Check your key

Every request carries your key in the X-API-Key header. A plain header, not a Bearer token.

curl -s https://api.reqbeat.com/v1/whoami -H "X-API-Key: $REQBEAT_API_KEY"

You get back your account id and tier. A 401 almost always means the header name is wrong.

2. Run your first search

Companies that opened sales roles in the United Kingdom:

curl -s "https://api.reqbeat.com/v1/reqs/search?role=sales&geo=United%20Kingdom&limit=5" -H "X-API-Key: $REQBEAT_API_KEY"

The response is a list of companies. Each row carries three things: the company (company_id and company_domain), the reqs that matched (matched_reqs: title, boards, first_seen date), and pulse (open req count, hiring velocity, direction, is_surge, momentum), precomputed on our side. The company name and HQ live on the enrichment endpoint, one call away. first_seen is the day we first detected the req on its source. That date is the point of the product: it tells you who to contact this morning, while you are the first or second voice instead of the ninth.

Two rules that save you ten minutes:

  • geo takes country names: United Kingdom, United States, Sweden. Common short codes like UK and GB resolve to the same thing. Cities and regions (London, England) are not geo values.
  • Useful filters: since (ISO date) for freshness, headcount_band for company size, industry, exclude_agencies=true to drop recruitment agencies from results, cursor for the next page.

For sharper targeting, POST /v1/reqs/qualified accepts structured criteria, live_only, and salary bounds.

3. Read one company deeply

Everything below takes the company_id you got from search.

curl -s https://api.reqbeat.com/v1/companies/COMPANY_ID/pre-action-brief -H "X-API-Key: $REQBEAT_API_KEY"

pre-action-brief is the one-call brief before you write or call: pulse, first hires by function, repost pain, top open reqs, and ATS changes, in one response. The rest of the company surface, each one endpoint: is-hiring, open-reqs (by function and country), hiring-pulse (velocity and direction), enrichment (name, domain, HQ, boards), first-hire (first hire in a function, a stage-change signal), repost-pain (roles reposted for weeks, public proof a company cannot fill them), ats-migrations, and intent (score).

4. Get pushed instead of polling

One call sets up the whole loop:

curl -s -X POST https://api.reqbeat.com/v1/quickstart -H "X-API-Key: $REQBEAT_API_KEY" -H "Content-Type: application/json" -d '{"webhook_url":"https://your-endpoint.example.com/hook","domain":"example.com"}'

quickstart returns working code snippets, a watch, and a webhook, wired together. Prefer to assemble it yourself: POST /v1/watches with a company_id or a criteria set plus event_types, POST /v1/webhooks for delivery, GET /v1/events if you would rather pull the event feed on your own schedule. Missed deliveries are replayable via /v1/webhook-deliveries/replay. Verifying delivery signatures is covered in the API reference.

5. Plug into your tools

Clay. A native endpoint, one column: POST /v1/clay/enrich with {"domain": "...", "name": "..."} returns is_hiring and open_req_count. Use it as a qualifier column before your enrichment waterfall, so credits are spent on companies that are hiring right now.

n8n, Make, or any HTTP node. One HTTP Request node, the X-API-Key header, and any search above. No SDK needed.

Claude and other MCP agents. The MCP server at mcp.reqbeat.com exposes who_is_hiring_for and works without a key. Clients must accept both content types:

curl -s -X POST https://mcp.reqbeat.com/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"who_is_hiring_for","arguments":{"role":"backend engineer","geo":"United Kingdom","limit":5}}}'

Your existing list. POST /v1/migration-import takes a CSV of companies and returns coverage: which of them are hiring right now, which we track, what you are missing.

6. Close the loop

When a signal turns into a meeting or a placement, log it: POST /v1/companies/{id}/outcomes. Then GET /v1/attribution reads results back (attributed_14d). This is how you prove, with your own numbers, that the dated rows above turn into revenue.

Account plumbing lives next door: GET /v1/usage for consumption, /v1/keys to create and rotate keys, /v1/account/pause and resume.

7. First-hour questions

401 on every call. The header is X-API-Key. Not Authorization, not Bearer.

Geo rejected. Use a country name: United Kingdom, not London or England. The error lists what is accepted.

How fresh is this? The corpus rebuilds every 3 hours, and every req carries its first_seen date, so you never have to guess.

More than one page. Take next_cursor from the response and pass it back as cursor.

8. Three things people build first

The morning list. reqs/search with your role and geo, since yesterday, sorted by is_surge. Companies that started hiring while you slept, as a call list.

The repost-pain opener. repost-pain on target accounts. A role reposted for six weeks is a company that needs help today, with proof attached.

The coverage audit. migration-import with the list you already work. Learn what share of it is hiring right now, before you spend another credit enriching the rest.

This page is the path to your first signal, nothing more. The full endpoint list, the field dictionary and the changelog live in the API reference, refreshed every 3 hours from the live API.