Create a watch

Create a watch. Watch a company domain (`type: company`) or a saved search filter (`type: search`).

Cost: FreeCreating a watch is free. Each job.opened event the watch delivers costs 1 credit, unless you already paid for that job; other events are free.

POST

/watches

const url = 'https://api.betterjobs.cc/v1/watches';
const options = {
  method: 'POST',
  headers: {
    'BetterJobs-Version': '2026-10-01',
    'Idempotency-Key': '7b8f2c4e-1a3d-4f5b-9c6e-0d2a4b6c8e1f',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"type":"company","domain":"acme-robotics.example","webhook_url":"https://hooks.northwind.example/betterjobs","events":["job.opened","job.closed","company.hiring_started","company.hiring_stopped"]}'
};

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/watches \
  --header 'Authorization: Bearer <token>' \
  --header 'BetterJobs-Version: 2026-10-01' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 7b8f2c4e-1a3d-4f5b-9c6e-0d2a4b6c8e1f' \
  --data '{ "type": "company", "domain": "acme-robotics.example", "webhook_url": "https://hooks.northwind.example/betterjobs", "events": [ "job.opened", "job.closed", "company.hiring_started", "company.hiring_stopped" ] }'

Watch a company domain (type: company) or a saved search filter (type: search). Matching events are delivered to webhook_url and appear in GET /events.

Authorizations

bearerAuth

Parameters

Header Parameters

BetterJobs-Version

string

Allowed values: 2026-10-01

Example

2026-10-01

Date-pinned API version. Changes within a version are additive only. Defaults to your account’s pinned version.

Idempotency-Key

string

<= 255 characters

Example

7b8f2c4e-1a3d-4f5b-9c6e-0d2a4b6c8e1f

Unique key (for example a UUID). Retrying with the same key and body returns the first response and never charges twice. Same key with a different body returns 409 idempotency_conflict.

Request Body^required

application/json

object

type

required

string

Allowed values: company search

domain

Required when type is company.

string

filters

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

webhook_url

required

string format: uri

events

Event types to deliver. Defaults to all job and company events.

Array<string>

Allowed values: job.opened job.reposted job.closed job.updated company.hiring_started company.hiring_stopped search.completed

Examples

Watch one company

{
  "type": "company",
  "domain": "acme-robotics.example",
  "webhook_url": "https://hooks.northwind.example/betterjobs",
  "events": [
    "job.opened",
    "job.closed",
    "company.hiring_started",
    "company.hiring_stopped"
  ]
}

Watch a saved search

{
  "type": "search",
  "filters": {
    "title_or": [
      "Head of RevOps"
    ],
    "country_code_or": [
      "DE",
      "AT",
      "CH"
    ]
  },
  "webhook_url": "https://hooks.northwind.example/betterjobs",
  "events": [
    "job.opened"
  ]
}

Responses

201

Watch created.

application/json

object

required

string

/^wat_/

type

required

string

Allowed values: company search

domain

required

string | null

filters

required

One of:

object
null

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

webhook_url

required

string format: uri

events

required

Array<string>

Allowed values: job.opened job.reposted job.closed job.updated company.hiring_started company.hiring_stopped search.completed

status

required

string

Allowed values: active paused

created_at

required

string format: date-time

Examples

company

Company watch

{
  "id": "wat_6Np3QyR8tU",
  "type": "company",
  "domain": "acme-robotics.example",
  "filters": null,
  "webhook_url": "https://hooks.northwind.example/betterjobs",
  "events": [
    "job.opened",
    "job.closed",
    "company.hiring_started",
    "company.hiring_stopped"
  ],
  "status": "active",
  "created_at": "2026-10-11T08:00:00Z"
}

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.

401

Missing or invalid API key.

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

unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "Missing or invalid API key. Send 'Authorization Bearer bj_live_...'.",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#unauthorized",
    "request_id": "req_5Dl6EvN0xY"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

403

Your plan does not include this feature or provider.

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

planRequired

{
  "error": {
    "type": "permission_error",
    "code": "plan_required",
    "message": "Provider 'coresignal' is not enabled on your plan. Pro and above include all six providers.",
    "required_plan": "pro",
    "upgrade_url": "https://betterjobs.cc/pricing",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#plan_required",
    "request_id": "req_7Fj4GtL8vW"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

409

Same Idempotency-Key reused with a different body.

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

idempotencyConflict

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_conflict",
    "message": "Idempotency-Key '7b8f2c4e-1a3d-4f5b-9c6e-0d2a4b6c8e1f' was used with a different request body.",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#idempotency_conflict",
    "request_id": "req_9Hh2IrJ6tU"
  }
}

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.

500

Something failed on our side. Safe to retry with the same Idempotency-Key.

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

internalError

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Unexpected error. Retry with the same Idempotency-Key; you will not be charged twice.",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#internal_error",
    "request_id": "req_1Jf0KpG4rS"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

Create a watch

Authorizations

Parameters

Header Parameters

Example

Example

Request Bodyrequired

Examples

Responses

201

Examples

Headers

Example

400

Examples

Headers

Example

401

Examples

Headers

Example

403

Examples

Headers

Example

409

Examples

Headers

Example

429

Examples

Headers

Example

Example

Example

Example

Example

500

Examples

Headers

Example

Request Body^required