Sandbox search (no key)

Sandbox search (no key). Same request and response shape as `POST /jobs/search`, no auth required.

Cost: FreeFree. Fixed illustrative data.

POST

/sandbox/jobs/search

const url = 'https://api.betterjobs.cc/v1/sandbox/jobs/search';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"filters":{"title_or":["Head of RevOps"],"country_code_or":["DE","AT","CH"],"posted_within_days":7},"limit":10}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.betterjobs.cc/v1/sandbox/jobs/search \
  --header 'Content-Type: application/json' \
  --data '{ "filters": { "title_or": [ "Head of RevOps" ], "country_code_or": [ "DE", "AT", "CH" ], "posted_within_days": 7 }, "limit": 10 }'

Same request and response shape as POST /jobs/search, no auth required. Returns fixed illustrative data. Nothing is charged and no provider is called.

Request Body^required

application/json

object

filters

required

Filter grammar with suffix operators. Unknown fields return 400 unknown_filter.

object

title_or

Match any of these title keywords.

Array<string>

title_not

Exclude titles containing any of these.

Array<string>

country_code_or

ISO 3166-1 alpha-2 codes.

Array<string>

posted_within_days

Jobs first seen within this many days.

integer

>= 1 <= 365

seniority_or

Array<string>

Allowed values: intern junior mid senior lead director vp c_level

employment_type_or

Array<string>

Allowed values: full_time part_time contract internship temporary

remote

true remote only, false non-remote only, null or omitted = any.

boolean | null

salary_min_gte

Keep jobs whose salary.min is at least this value (yearly, in the job’s currency). Jobs with salary null are excluded when set.

number

company_domain_or

Array<string>

job_family_or

Array<string>

include_closed

Include jobs with status: closed.

boolean

waterfall

How BetterJobs routes the request across providers.

object

strategy

cheapest_first stops once enough unique jobs are found, starting with the BetterJobs index. freshest_first tries the sources with the fastest refresh first. max_coverage queries every provider on your plan. consensus returns only jobs seen by at least min_sources sources. own_only uses the BetterJobs index only.

string

default: cheapest_first

Allowed values: cheapest_first freshest_first max_coverage consensus own_only

providers

Override the providers to query. Must be enabled on your plan.

Array<string>

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

max_credits

Hard cap on credits this request may charge. Results stop at the cap.

integer

timeout_ms

Per-request time budget. Slow providers are dropped and the result is partial.

integer

default: 10000 >= 1000 <= 30000

min_sources

Minimum agreeing sources for consensus.

integer

default: 2 >= 2 <= 7

limit

integer

default: 25 >= 1 <= 100

cursor

next_cursor from the previous page.

string

dry_run

Return a free estimate without fetching.

boolean

Examples

hello

{
  "filters": {
    "title_or": [
      "Head of RevOps"
    ],
    "country_code_or": [
      "DE",
      "AT",
      "CH"
    ],
    "posted_within_days": 7
  },
  "limit": 10
}

Responses

200

Fixed illustrative results.

application/json

object

data

required

Array<object>

A canonical job: one real opening, merged from every source that saw it. Null semantics: null = unknown; [] = verified none; field omitted = not part of this payload (for example the lifecycle-only job in job.closed and job.reposted events).

object

required

Canonical job id. Stable across sources and requests.

string

/^job_/

title

required

string

company

required

Company reference embedded in jobs, events and profiles.

object

required

string

/^cmp_/

name

required

string

domain

required

Primary web domain. null when unknown.

string | null

location

required

object

city

required

string | null

region

required

string | null

country_code

required

ISO 3166-1 alpha-2.

string | null

remote

required

true remote, false on-site or hybrid, null unknown.

boolean | null

employment_type

required

One of:

string
null

string

Allowed values: full_time part_time contract internship temporary

seniority

required

One of:

string
null

string

Allowed values: intern junior mid senior lead director vp c_level

job_family

required

string | null

salary

required

One of:

object
null

object

min

required

number | null

max

required

number | null

currency

required

ISO 4217.

string

period

required

string

Allowed values: year month hour

origin

required

declared = stated in the posting. inferred = estimated by a source.

string

Allowed values: declared inferred

description

required

Plain-text job description.

string | null

apply_url

required

string | null format: uri

posted_at

required

Date the employer posted the job, if known.

string | null format: date-time

first_seen_at

required

Earliest time any source saw the job.

string format: date-time

last_seen_at

required

Latest time any source saw the job.

string format: date-time

last_verified_at

required

Latest time the job was confirmed live at its origin.

string | null format: date-time

status

required

string

Allowed values: open closed

closed_reason

required

Why the job closed. null while open.

string | null

Allowed values: filled expired removed unknown

repost_count

required

Times the same job was re-listed.

integer

p_real

required

Probability (0-1) that the job is a real open req, from cross-source corroboration.

number

<= 1

sources

required

Array<object>

One provider’s view of the canonical job.

object

provider

required

Source slug. betterjobs is the BetterJobs index.

string

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

provider_job_id

required

string

url

required

string | null format: uri

first_seen_at

required

string format: date-time

last_seen_at

required

string format: date-time

fields

required

Job fields this source contributed to the canonical record.

Array<string>

license

required

object

display

required

You may show this job to your end users.

boolean

resale

required

You may resell or redistribute this job as data.

boolean

next_cursor

required

Pass as cursor for the next page. null = last page.

string | null

metadata

required

object

request_id

required

string

status

required

partial = at least one provider failed or timed out. You are billed only for returned jobs.

string

Allowed values: complete partial

credits_charged

required

integer

jobs_already_paid

required

Returned jobs you had already paid for (free).

integer

duplicates_merged

required

Provider records merged into existing canonical jobs (free).

integer

credits_remaining

required

integer

providers

required

object

tried

required

Array<string>

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

hit

required

Providers that returned at least one match.

Array<string>

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

failed

required

Array<object>

object

provider

required

Source slug. betterjobs is the BetterJobs index.

string

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

code

required

provider_timeout = the provider missed timeout_ms. provider_error = the provider returned an error.

string

Allowed values: provider_timeout provider_error

contributions

required

Unique jobs each provider contributed first.

object

key

additional properties

integer

field_coverage

required

Fraction (0-1) of returned jobs with a non-null value, per field.

object

key

additional properties

number

<= 1

latency_ms

required

integer

Examples

sandbox

{
  "data": [
    {
      "id": "job_01JC8X4M2Q7RV3T9KD5W6YH0AB",
      "title": "Head of Revenue Operations",
      "company": {
        "id": "cmp_4Rk7TzP1aQ",
        "name": "Acme Robotics",
        "domain": "acme-robotics.example"
      },
      "location": {
        "city": "Berlin",
        "region": "Berlin",
        "country_code": "DE",
        "remote": false
      },
      "employment_type": "full_time",
      "seniority": "lead",
      "job_family": "operations",
      "salary": {
        "min": 110000,
        "max": 135000,
        "currency": "EUR",
        "period": "year",
        "origin": "declared"
      },
      "description": "Acme Robotics is hiring a Head of Revenue Operations to own forecasting, CRM hygiene and the GTM tool stack across DACH.",
      "apply_url": "https://jobs.acme-robotics.example/revops-lead/apply",
      "posted_at": "2026-10-08T00:00:00Z",
      "first_seen_at": "2026-10-08T06:40:00Z",
      "last_seen_at": "2026-10-11T06:10:00Z",
      "last_verified_at": "2026-10-11T06:10:00Z",
      "status": "open",
      "closed_reason": null,
      "repost_count": 0,
      "p_real": 0.94,
      "sources": [
        {
          "provider": "betterjobs",
          "provider_job_id": "bj_idx_5521907",
          "url": "https://jobs.acme-robotics.example/revops-lead",
          "first_seen_at": "2026-10-08T06:40:00Z",
          "last_seen_at": "2026-10-11T06:10:00Z",
          "fields": [
            "title",
            "description",
            "apply_url",
            "location",
            "employment_type",
            "posted_at"
          ]
        },
        {
          "provider": "theirstack",
          "provider_job_id": "ts_88213377",
          "url": "https://jobs.acme-robotics.example/revops-lead",
          "first_seen_at": "2026-10-08T07:12:00Z",
          "last_seen_at": "2026-10-11T04:02:00Z",
          "fields": [
            "salary",
            "seniority"
          ]
        },
        {
          "provider": "techmap",
          "provider_job_id": "tm_3f9a2c71",
          "url": "https://boards.example/acme-robotics/revops-lead",
          "first_seen_at": "2026-10-08T09:30:00Z",
          "last_seen_at": "2026-10-10T23:40:00Z",
          "fields": [
            "job_family"
          ]
        }
      ],
      "license": {
        "display": true,
        "resale": false
      }
    }
  ],
  "next_cursor": null,
  "metadata": {
    "request_id": "req_sandbox_0001",
    "status": "complete",
    "credits_charged": 0,
    "jobs_already_paid": 0,
    "duplicates_merged": 2,
    "credits_remaining": 0,
    "providers": {
      "tried": [
        "betterjobs",
        "techmap",
        "theirstack"
      ],
      "hit": [
        "betterjobs",
        "techmap",
        "theirstack"
      ],
      "failed": [],
      "contributions": {
        "betterjobs": 1,
        "techmap": 0,
        "theirstack": 0
      }
    },
    "field_coverage": {
      "salary": 1,
      "seniority": 1,
      "location.remote": 1,
      "description": 1
    },
    "latency_ms": 12
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

400

Invalid request (invalid_request) or unknown filter field (unknown_filter).

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error billing_error permission_error not_found_error conflict_error rate_limit_error api_error

code

required

string

Allowed values: invalid_request unknown_filter unauthorized insufficient_credits plan_required not_found idempotency_conflict rate_limited internal_error

message

required

string

doc_url

required

string format: uri

request_id

required

string

credits_needed

Present on insufficient_credits.

integer

required_plan

string

Allowed values: free starter growth pro scale enterprise

upgrade_url

Present on insufficient_credits and plan_required.

string format: uri

param

Offending field on invalid_request and unknown_filter.

string

key

additional properties

any

Examples

unknown_filter

{
  "error": {
    "type": "invalid_request_error",
    "code": "unknown_filter",
    "message": "Unknown filter field 'job_title_or'. Did you mean 'title_or'?",
    "param": "filters.job_title_or",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#unknown_filter",
    "request_id": "req_4Bn8CxV2zA"
  }
}

invalid_request

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "limit must be between 1 and 100.",
    "param": "limit",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#invalid_request",
    "request_id": "req_2Cm7DwB1yZ"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

429

Too many requests. Wait Retry-After seconds.

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error billing_error permission_error not_found_error conflict_error rate_limit_error api_error

code

required

string

Allowed values: invalid_request unknown_filter unauthorized insufficient_credits plan_required not_found idempotency_conflict rate_limited internal_error

message

required

string

doc_url

required

string format: uri

request_id

required

string

credits_needed

Present on insufficient_credits.

integer

required_plan

string

Allowed values: free starter growth pro scale enterprise

upgrade_url

Present on insufficient_credits and plan_required.

string format: uri

param

Offending field on invalid_request and unknown_filter.

string

key

additional properties

any

Examples

rateLimited

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#rate_limited",
    "request_id": "req_0Ig1JqH5sT"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

Retry-After

integer

Example

Seconds to wait before retrying.

RateLimit-Limit

integer

Example

Requests allowed in the current window.

RateLimit-Remaining

integer

Example

Requests left in the current window.

RateLimit-Reset

integer

Example

Seconds until the window resets.

Sandbox search (no key)

Request Bodyrequired

Examples

Responses

200

Examples

Headers

Example

400

Examples

Headers

Example

429

Examples

Headers

Example

Example

Example

Example

Example

Request Body^required