Field dictionary

One complete record

A real job from the live API on October 14, 2026, requested with include=company,source_data. Only the description text is shortened, and the company.identifiers and company.industries entries are the values Headcount Labs returned for this employer. next_cursor and snapshot_watermark sit beside data on list responses; a single-job response holds only data.

{
  "data": [
    {
      "job_id": "9f70ad16-ab51-49fe-b964-62067a7946b3",
      "currentness": "current",
      "stale": false,
      "company_id": "3483b509-5f22-4535-a907-19c285f3b460",
      "employer_name": {
        "state": "known",
        "value": "Cloudflare"
      },
      "title": {
        "state": "known",
        "value": "Senior Customer Engineer, Strategic - San Francisco"
      },
      "description": {
        "state": "known",
        "value": "(plain-text job description, left out here for length)"
      },
      "work_arrangement": {
        "state": "known",
        "value": "hybrid"
      },
      "locations": [
        {
          "state": "known",
          "value": {
            "city": "San Francisco",
            "region": "US-CA",
            "country": "US",
            "county_fips": "06075",
            "msa": {
              "type": "metro",
              "cbsa_code": "41860",
              "cbsa_title": "San Francisco-Oakland-Fremont, CA"
            }
          }
        }
      ],
      "job_first_seen_at": "2026-10-07T19:31:45.114Z",
      "curated_at": "2026-10-13T07:33:18.049Z",
      "job_updated_at": "2026-10-14T23:30:26.947Z",
      "postings": [
        {
          "posting_id": "79de47fa11a25e23ad485762a9a0fb1c09cca32f3ae3c108b7788734134d504c",
          "source": "greenhouse",
          "source_posting_id": "8246078",
          "posting_status": "listed",
          "posting_url": {
            "state": "known",
            "value": "https://boards.greenhouse.io/cloudflare/jobs/8246078?gh_jid=8246078"
          },
          "application_url": {
            "state": "known",
            "value": "https://boards.greenhouse.io/cloudflare/jobs/8246078?gh_jid=8246078"
          },
          "location": {
            "state": "known",
            "value": {
              "city": "San Francisco",
              "state": "CA",
              "remote": false,
              "country": "US"
            }
          },
          "pay": {
            "state": "known",
            "value": {
              "max": 336000,
              "min": 214000,
              "currency": "USD",
              "interval": "year"
            }
          },
          "source_posted_at": "2026-10-06T14:22:31.000Z",
          "first_seen_at": "2026-10-07T19:31:45.114Z",
          "last_completed_fetch_at": "2026-10-14T14:04:07.098Z",
          "latest_application_check": null,
          "attribution": {
            "required": null,
            "text": null,
            "link": null
          },
          "source_data": {
            "job_location_type": "hybrid",
            "source_posted_at": "2026-10-06T14:22:31.000Z",
            "source_updated_at": "2026-10-14T00:57:01.000Z",
            "employment_type": null,
            "source_type": "greenhouse",
            "availability": "listed"
          }
        }
      ],
      "company": {
        "company_id": "3483b509-5f22-4535-a907-19c285f3b460",
        "name": "Cloudflare",
        "country": "US",
        "status": "active",
        "region": "CA",
        "address_source": "sec",
        "identifiers": [
          {
            "scheme": "ein",
            "value": "270805829",
            "exchange": null,
            "source": "sec"
          },
          {
            "scheme": "sec_cik",
            "value": "0001477333",
            "exchange": null,
            "source": "sec"
          },
          {
            "scheme": "ticker",
            "value": "NET",
            "exchange": null,
            "source": "sec"
          },
          {
            "scheme": "uei",
            "value": "JV9YXS9MLA48",
            "exchange": null,
            "source": "sam_gov"
          }
        ],
        "industries": [
          {
            "system": "naics",
            "code": "541519",
            "source": "sam_gov"
          },
          {
            "system": "sic",
            "code": "7372",
            "source": "sec"
          }
        ]
      }
    }
  ],
  "next_cursor": "<opaque cursor, or null on the last page>",
  "snapshot_watermark": "2026-10-14T01:43:41.000Z"
}

How to read a value

Most text-like fields are wrapped in a small object that says where the value came from. Read state first and only then look for value.

A state is never the same as null. Treat source_omitted and extraction_failed as "unknown", and keep them apart from a known empty value.

Job fields

Posting fields

Each entry in postings is one listing of the job on one source.

Locations

A job has two kinds of location data, and they use different keys.

Job level (locations[].value) is cleaned and enriched. Keys: city, region (ISO 3166-2, for example US-TX), country (two letters), county_fips (a five-digit US county code as a string, or null), msa and, when the source gives them, street and postal_code. msa is {"type":"metro" or "micro","cbsa_code","cbsa_title"}, or null when the place is in no statistical area. zip is a five-digit US ZIP, present only when the posting states a real ZIP inside the stated state; the key is absent otherwise.

Posting level (postings[].location.value) is the source’s own data, so keys follow what the source publishes: city, state, remote (boolean) and country, plus, when the source gives them, latitude, longitude, postalCode, streetAddress, countryRaw, regionCode and zip. A posting that lists several places also has alternatives, an array where each entry has raw, city, state, remote, country and the same optional keys.

Pay

postings[].pay.value holds min, max, currency (ISO 4217) and interval (year, month or hour), as the source published them. When a source lists several ranges, ranges is an array of the same four keys. Pay is never converted between currencies or intervals in the response. The filters pay_min and pay_max compare yearly amounts: hourly pay is multiplied by 2,080 and monthly pay by 12 before comparing, and pay with an unknown interval never matches. When there is no pay, the state is source_omitted, or extraction_failed where a pay line could not be read.

Company object

Ask for it with include=company. Each company has company_id, name, country and status (active, retired or merged), plus:

Source data

With include=source_data each posting gets a source_data object with the values the source itself labels. It holds only the keys below; the raw source payload is not published.

Other response shapes

Value lists

Counts below are current jobs from the October 14, 2026 snapshot (4,886,218 current jobs). They change daily. Run GET /v1/jobs/count with the filter to see today’s number.

Employment type is free text

employment_type is the label the source printed, so the same idea appears under many spellings. A filter matches one spelling exactly, ignoring case. These are the most common ones:

There is no normalized list. To cover one idea, send several spellings in one filter: employment_type takes up to 10 values. Use GET /v1/jobs/count?employment_type=... to test a spelling before you rely on it. A count over several very common spellings with no other filter can run past the 10-second limit and return 504 query_timeout; add a country or state to narrow it.