# TheirStack

> What does TheirStack contribute, and when does BetterJobs route to it?

Source: https://docs.betterjobs.cc/providers/theirstack/

TheirStack sells global job postings with technographics, buying intent and firmographics on top. BetterJobs uses it as one of six partner providers.

TheirStack

`theirstack`

Global job postings, technographics inferred from job text, buying intent and firmographics.

- Coverage

  Global job postings; no person data

- Discovery

  73% of jobs discovered the same day, 91% by the end of the next day

- Credits

  1 API credit per job, 3 per company

- Re-fetch

  Re-fetching the same job is billed again (filter discovered\_at\_gte)

Growth includes 2 partner providers; Pro and above include all six. GET /v1/providers shows what your plan enables.

Facts per TheirStack docs.

## What it is strong at

All facts in this section are per TheirStack docs.

- **Global postings.** Job postings worldwide. No person data.
- **Technographics.** The tech a company uses, inferred from the text of its job posts.
- **Buying intent and firmographics** at company level.
- **Fast discovery.** 73% of jobs are discovered the same day and 91% by the end of the next day.
- **Webhooks.** `job.new`, `job.closed` and `company.new`.

## What it contributes to a BetterJobs job

TheirStack’s field names next to ours:

| BetterJobs                | TheirStack              |
| ------------------------- | ----------------------- |
| `title`                   | `job_title`             |
| `company.domain`          | `company_domain`        |
| `location.remote`         | `remote`                |
| `seniority`               | `seniority`             |
| `salary`                  | `salary_string`         |
| `salary.min`              | `min_annual_salary_usd` |
| `posted_at`               | `date_posted`           |
| `first_seen_at`           | `discovered_at`         |
| `sources[].url`           | `url`                   |
| `sources[].first_seen_at` | `discovered_at`         |

What TheirStack filled on a given job is in that job’s `sources[]` entry for `theirstack`, under `fields`. In the spec’s illustrative example it supplied `salary` and `seniority` to a job the BetterJobs index found first.

Technographics, buying intent and firmographics are not part of the v1 job schema. You get the job, not TheirStack’s company enrichment.

## Refresh

Per TheirStack docs, 73% of jobs are discovered the same day and 91% by the end of the next day. Their `discovered_at` maps to `sources[].first_seen_at` for the `theirstack` entry, and feeds the job’s `first_seen_at` when TheirStack saw it first.

## Notes and quirks we normalize

### Re-fetching is billed again there, not here

Per TheirStack docs, it charges 1 API credit per job and 3 per company, and re-fetching the same job is billed again. Their advice is to filter on `discovered_at_gte` so you only pull new jobs.

Through BetterJobs you do not need that workaround. You pay 1 credit for a unique job once. A job you already paid for is free on every later search or `GET /v1/jobs/{id}`. It counts in `metadata.jobs_already_paid`, and `GET /v1/billing/ledger?job_id=...` shows the charge and the free re-reads. See [Credits and billing](https://docs.betterjobs.cc/concepts/credits-and-billing.md).

A BetterJobs [company profile](https://docs.betterjobs.cc/data/companies.md) costs 1 credit.

### Same suffix grammar, different field names

TheirStack filters use suffixes: `_or`, `_not`, `_gte` / `_lte`, `_max_age_days`. BetterJobs uses the same suffix style, so most queries translate directly. The field names differ.

| You write for TheirStack | You write for BetterJobs |
| ------------------------ | ------------------------ |
| `job_title_or`           | `title_or`               |
| `job_title_not`          | `title_not`              |
| `company_domain_or`      | `company_domain_or`      |
| `*_max_age_days`         | `posted_within_days`     |

> Old names fail loudly
>
> BetterJobs rejects unknown filter fields. Sending `job_title_or` returns `400 unknown_filter` with `"Did you mean 'title_or'?"` and `param: filters.job_title_or`. It is never silently ignored. See [unknown\_filter](https://docs.betterjobs.cc/platform/errors.md#unknown_filter) and the full list in [Filters](https://docs.betterjobs.cc/platform/filters.md).

The full translation, with a worked query, is in [Migrate from TheirStack](https://docs.betterjobs.cc/guides/migrate-from-theirstack.md).

### Salary in many shapes

TheirStack reports pay as `salary_string` and as `min_annual_salary_usd`. BetterJobs returns one `salary` object: `min`, `max`, `currency`, `period` and `origin` (`declared` or `inferred`). See [`salary`](https://docs.betterjobs.cc/data/field-dictionary.md#field-job-salary).

### Webhooks

TheirStack’s `job.new` and `job.closed` correspond to BetterJobs [`job.opened`](https://docs.betterjobs.cc/data/events.md#event-job-opened) and [`job.closed`](https://docs.betterjobs.cc/data/events.md#event-job-closed). BetterJobs events come from the merged job, not from one provider. See [Webhooks](https://docs.betterjobs.cc/platform/webhooks.md).

## When BetterJobs routes to it

Only when TheirStack is enabled on your plan. Then:

- `max_coverage` asks it on every search.
- `cheapest_first` asks it only if the BetterJobs index and earlier sources did not fill the page.
- `waterfall.providers: ["betterjobs", "theirstack"]` pins it.

Check `metadata.providers.tried` and `metadata.providers.hit` to see whether it was asked and matched.

## Plans that include it

Growth includes 2 partner providers; Pro and above include all six. GET /v1/providers shows what your plan enables. See the [plan table](https://docs.betterjobs.cc/providers.md#which-plan-includes-which-provider).

## Provider docs

We do not link to TheirStack’s docs from this site. Everything you need to use TheirStack data through BetterJobs is on this page and in [Migrate from TheirStack](https://docs.betterjobs.cc/guides/migrate-from-theirstack.md).

## Related

- [Migrate from TheirStack](https://docs.betterjobs.cc/guides/migrate-from-theirstack.md)
- [All providers](https://docs.betterjobs.cc/providers.md)
- [Field dictionary](https://docs.betterjobs.cc/data/field-dictionary.md)
