# Hiring Signals

> Look up a company's hiring signals by domain, or find companies hiring for a given kind of role.

Source page: https://docs.replynodes.com/docs/guides/hiring-signals

# Hiring signals

Hiring signals turn open job listings into a per-company picture an agent can act on: how many roles are open, how many were posted recently, which functions and seniorities, where, and how long roles have been open. Two read operations share one precomputed dataset:

- `GET /v1/jobs/company` returns the signals for one domain.
- `GET /v1/jobs/companies` finds companies with matching open roles.

The dataset currently covers companies hiring through Ashby. Greenhouse and Lever are added without changing the response shape: every response lists the `sources` in the build and the `source_freshness` of each. Coverage is partial and strongest for larger employers, so treat a miss as "not in the dataset", never as "not hiring".

## Look up one company

```bash
curl -sS "https://api.replynodes.com/v1/jobs/company?domain=https://www.acme.com/careers"
```

`domain` accepts a bare domain or a URL and is reduced to the registrable domain (`acme.com`). `sample_jobs` (0 to 3, default 3) controls how many example roles are returned. The response always carries `coverage`:

| `coverage` | Meaning |
| --- | --- |
| `covered` | The domain is in the dataset and has open roles. `company` and `signals` are filled in. |
| `no_open_roles` | The domain is in the dataset but has no open roles now. Counts are zero. |
| `not_in_dataset` | The domain is not in the dataset. This is not evidence that the company is not hiring. `sources` lists what is covered. |

`signals` contains `open_roles`, `new_roles_7d`, `new_roles_30d`, `roles_open_30d_plus`, `roles_open_60d_plus`, `oldest_open_role_days`, `by_function`, `by_seniority`, `top_locations`, `workplace`, `salary_ranges`, `sample_jobs` and a template `signal_summary`. No language model is involved: the summary is a fixed template over the counts. Every response also carries `data_as_of` (the oldest snapshot time among the sources), `computed_at` and `classifier_version`.

A few definitions worth knowing:

- Dates come from the source's posted date. When it is missing or unusable the first-seen date is used and `posted_at_fallback` is true. Roles that were already open when the dataset was first loaded are never counted as new.
- `workplace` uses the source's own workplace type: `remote`, `hybrid` and `onsite` are distinct, and anything without a workplace type is `unknown`. It is never guessed from the location text. This differs deliberately from `remote=true` on `GET /v1/jobs/search`, which also matches hybrid roles.
- Function and seniority come from a versioned keyword list, not a model. Seniority is `unspecified` when the title has no level keyword. Expect occasional misclassification; `classifier_version` identifies the list that produced a result.

## Find companies

```bash
curl -sS -H "Authorization: Bearer $REPLYNODES_API_KEY" \
  "https://api.replynodes.com/v1/jobs/companies?function=sales&countries=US&posted_within_days=30&min_roles=2&limit=10"
```

All filters apply to the **same role**: a company is returned when at least `min_roles` of its open roles satisfy every supplied filter together, and `matching_roles` counts only those roles. The filters are `function`, `seniority` and `countries` (comma-separated lists), `workplace` (`remote`, `hybrid`, `onsite` or `any`), `posted_within_days` (7, 14, 30 or 90), `open_min_days` (roles open at least this long), `min_roles`, and `max_open_roles` (a size proxy applied to the company's total). `open_min_days` greater than `posted_within_days` is rejected with `400`.

Results are ordered by `sort` (`new_roles`, `matching_roles` or `oldest_open`) and then by domain, so the same query returns the same order. `limit` is 1 to 25. When more results exist, `meta.next_cursor` is an opaque cursor bound to the current data build; send it back as `cursor` with the same filters. A cursor from an older build returns `409 stale_cursor` at no charge: restart without it.

## Segments

- **Sales and GTM personalisation:** `function=sales&posted_within_days=30` finds companies investing in a sales team; open a lookup per company for a one-line `signal_summary`.
- **Developer-tool intent:** `function=engineering&seniority=senior,staff_principal&workplace=remote` finds companies growing senior remote engineering.
- **Recruiting and staffing:** `open_min_days=60` finds hard-to-fill roles.
- **Research and market mapping:** `sort=matching_roles` with `countries` ranks the most active employers in a market.
- **Outsourcing and vendors:** `function=security&max_open_roles=50` finds smaller companies building a function they might buy.

## Billing and limits

`jobs/company` costs 5 credits for `covered` and `no_open_roles`, and nothing for `not_in_dataset`. `jobs/companies` costs 10 credits per successful call, including an empty result, and always needs an API key. Errors cost nothing. Both use the gateway's durable hold and idempotency identity. A settled answer is replayed without charging again, whether you repeat the identical request or send the same `X-Idempotency-Key`. Without a key, a request that failed or was answered free (`not_in_dataset`) is simply run again when you repeat it, so a transient outage or a company added later does not leave that query stuck; with a key, the original outcome is kept for that key and you send a new key to run it fresh. A settled answer is replayed only while the gateway still holds the stored response; if it has expired, repeat the request with a new `X-Idempotency-Key`.

`jobs/company` also works without a key, within its own anonymous tier of 10 lookups per client per UTC day. Every anonymous lookup counts, including `not_in_dataset` answers. When the limit is reached the response is `429 anonymous_limit_reached`; an API key lifts it.

## MCP

The same operations are exposed by the canonical MCP tools `company_hiring_signals` and `hiring_companies_search`, which forward to these REST routes. The [API Reference](https://docs.replynodes.com/reference) contains the complete field and error schemas.
