Get a company hiring profile

Get a company hiring profile. Hiring profile for one company domain.

Cost: 1 credit / request1 credit per profile.

GET

/companies/{domain}

const url = 'https://api.betterjobs.cc/v1/companies/acme-robotics.example';
const options = {
  method: 'GET',
  headers: {'BetterJobs-Version': '2026-10-01', Authorization: 'Bearer <token>'}
};

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

curl --request GET \
  --url https://api.betterjobs.cc/v1/companies/acme-robotics.example \
  --header 'Authorization: Bearer <token>' \
  --header 'BetterJobs-Version: 2026-10-01'

Hiring profile for one company domain. is_hiring.value is true, false or null. null means unknown. Never treat null as false.

Authorizations

bearerAuth

Parameters

Path Parameters

domain

required

string

Example

acme-robotics.example

Company domain, without scheme or path.

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.

Responses

200

Company hiring profile.

application/json

object

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

open_jobs_count

required

integer

is_hiring

required

object

value

required

null = unknown. Never treat null as false.

boolean | null

confidence

required

number

<= 1

basis

required

Plain-English reason for the value.

string

hiring_pulse

required

object

direction

required

string

Allowed values: up flat down

open_jobs_30d_change

required

Change in open jobs over the last 30 days.

integer

top_job_families

required

Array<object>

object

job_family

required

string

open_jobs

required

integer

sources

required

Array<object>

object

provider

required

Source slug. betterjobs is the BetterJobs index.

string

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

open_jobs

required

integer

last_seen_at

required

string format: date-time

Examples

Company that is hiring

{
  "company": {
    "id": "cmp_4Rk7TzP1aQ",
    "name": "Acme Robotics",
    "domain": "acme-robotics.example"
  },
  "open_jobs_count": 42,
  "is_hiring": {
    "value": true,
    "confidence": 0.96,
    "basis": "42 open jobs corroborated by 4 sources in the last 30 days"
  },
  "hiring_pulse": {
    "direction": "up",
    "open_jobs_30d_change": 9
  },
  "top_job_families": [
    {
      "job_family": "engineering",
      "open_jobs": 18
    },
    {
      "job_family": "sales",
      "open_jobs": 11
    },
    {
      "job_family": "operations",
      "open_jobs": 6
    }
  ],
  "sources": [
    {
      "provider": "betterjobs",
      "open_jobs": 38,
      "last_seen_at": "2026-10-11T06:10:00Z"
    },
    {
      "provider": "theirstack",
      "open_jobs": 31,
      "last_seen_at": "2026-10-11T04:02:00Z"
    },
    {
      "provider": "techmap",
      "open_jobs": 27,
      "last_seen_at": "2026-10-10T23:40:00Z"
    },
    {
      "provider": "coresignal",
      "open_jobs": 25,
      "last_seen_at": "2026-10-10T18:15:00Z"
    }
  ]
}

Not enough signal (unknown, not "not hiring")

{
  "company": {
    "id": "cmp_9Hs2VbN6eW",
    "name": "Northwind Traders",
    "domain": "northwind.example"
  },
  "open_jobs_count": 0,
  "is_hiring": {
    "value": null,
    "confidence": 0,
    "basis": "No careers page or ATS found for this domain"
  },
  "hiring_pulse": {
    "direction": "flat",
    "open_jobs_30d_change": 0
  },
  "top_job_families": [],
  "sources": []
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

X-Credits-Charged

integer

Example

Credits charged by this request.

X-Credits-Remaining

integer

Example

Credits left on your account after this request.

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.

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.

402

Not enough credits for this request.

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

insufficientCredits

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "This request needs at least 25 credits; 3 remain.",
    "credits_needed": 25,
    "upgrade_url": "https://betterjobs.cc/pricing",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#insufficient_credits",
    "request_id": "req_6Ek5FuM9wX"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

404

The resource does not exist.

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

notFound

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "No job with id 'job_01JC00000000000000000000XX'.",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#not_found",
    "request_id": "req_8Gi3HsK7uV"
  }
}

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.