# JobsPipe API vocabulary. The words the API uses, and what each one means in it. Field names in
# the OpenAPI document (https://jobspipe.dev/openapi.json) use these terms and no synonyms for them.
# Maintained by JobsPipe. method: published
vocabulary:
  name: JobsPipe API Vocabulary
  version: "2026-10-25"
  maintainer: JobsPipe <support@jobspipe.dev>
  conventions:
    field_case: snake_case
    path_case: kebab-case, versioned under /v1/
    operation_id_case: lowerCamelCase
    timestamps: RFC 3339 in UTC, except last_seen_at and verified_at (YYYY-MM-DD HH:MM:SS, UTC)
    country: ISO 3166-1 alpha-2 (country_code, hq_country)
    currency: ISO 4217 (salary_currency); every *_usd field is converted to US dollars
    language: ISO 639-1, lowercase
  terms:
    - term: job
      definition: One job posting as published by an employer, agency or job board, normalized into one schema. The Job object.
    - term: id
      definition: The posting's ID on the source JobsPipe attributes it to. Opaque; its format varies by source. Stable for the same posting over time.
    - term: source
      definition: A job board, applicant tracking system or public employment service JobsPipe collects postings from. Listed in sources[] with the provider, URL and when it was seen.
    - term: status
      definition: Lifecycle state of a posting, active or closed.
    - term: closed_reason
      definition: Why a posting closed. closed - the source said so; gone - the posting disappeared; stale - unseen long enough to be treated as closed.
    - term: discovered_at
      definition: When JobsPipe first saw the posting.
    - term: last_seen_at
      definition: When JobsPipe last saw the posting live, on a collection run or a recheck.
    - term: verified_at
      definition: When JobsPipe last updated the posting's status.
    - term: employer_type
      definition: Who posted the job. employer - hires for itself; agency - a staffing or recruitment firm posting for a client; broker - a job board republishing another company's listing.
    - term: work_arrangement
      definition: How the role is worked, remote, hybrid or onsite. Null when the posting does not say.
    - term: seniority
      definition: The level of the role as labelled from the title and text, for example entry, mid, senior, lead, director.
    - term: occupation_code
      definition: The ISCO-08 unit group of the role (4 digits), for example 2512 = Software Developers.
    - term: isic_division
      definition: The ISIC Rev.4 industry division of the employer (2 digits), for example 62 = Computer programming and consultancy.
    - term: metro_code
      definition: The US Core Based Statistical Area (CBSA) code resolved from the job's location.
    - term: esco_skills
      definition: ESCO skill concepts for the skills extracted from a posting, as stable id and label pairs.
    - term: ghost_score
      definition: 0-100 likelihood that a posting is stale or evergreen rather than a live vacancy.
    - term: visa_sponsorship
      definition: The visa stance parsed from the posting, offers, no or citizenship_required.
    - term: company key
      definition: JobsPipe's stable identifier for a company (key). Pass it to company endpoints and to the company_key_or filter.
    - term: lei
      definition: The ISO 17442 Legal Entity Identifier of a company, where one is known.
    - term: technology
      definition: A product, language, framework or service, identified by its slug, that postings ask for or a website runs.
    - term: tier
      definition: How strong the evidence is that a company uses a technology. confirmed - two independent checks agree on at least one posting; likely - a required-strength mention or two postings; mentioned - a single mention.
    - term: monitor
      definition: A list of records the caller follows. JobsPipe sends their events (job.closed) to one of the caller's webhooks until the monitor expires.
    - term: signal
      definition: A saved search JobsPipe runs for the caller, which reports new matches by email or webhook (alert.matched).
    - term: webhook
      definition: An HTTPS endpoint of the caller's that JobsPipe signs and POSTs events to.
    - term: credit
      definition: "The unit an account's plan allowance is counted in: one credit buys one job (or one company) returned, for the rest of the calendar month in UTC. An empty result costs nothing. Responses report credits_charged and credits_remaining."
    - term: sandbox
      definition: Keyless endpoints under /v1/sandbox that return fixed sample data, for trying the API.