The job object

Search, the feeds, company jobs and single-job lookup all return this shape. Use id, a stable UUID, as your primary key for upserts.

Fields

Field	Type	Nullable	Description
`id`	uuid	No	Stable job identifier. Use it as your primary key.
`external_id`	string	Optional	The posting’s ID on its source platform. Omitted when unavailable (see External ID).
`title`	string	No	Job title as the employer lists it.
`normalized_title`	string \| null	Yes	Canonical snake_case title, e.g. `software_engineer`.
`occupation`	object \| null	Yes	The kind of work, from the occupation taxonomy (see Occupation).
`company`	object	No	The employer (see Company).
`description`	string	No	Cleaned description, Markdown by default (see Description format).
`language`	string \| null	Yes	Lowercase ISO 639-1 code of the description (`en`, `de`, `fr`, …).
`summary`	string \| null	Yes	AI-generated summary. Null until a newly indexed job is summarized.
`listing_url`	string	No	Direct URL to the original posting.
`apply_url`	string	No	Deep link to the application form. Can equal `listing_url` when there’s no separate apply flow.
`locations`	object[]	No	Job locations (see Location).
`compensation`	object \| null	Yes	Pay as the employer published it (see Compensation).
`employment_type`	string \| null	Yes	See Employment type.
`workplace_type`	string \| null	Yes	See Workplace type.
`experience_level`	string \| null	Yes	Seniority (see Experience level).
`source`	string	No	Platform the posting came from (see Source).
`created_at`	datetime	No	When Jobo first indexed the job.
`updated_at`	datetime	No	When Jobo last updated the job record.
`date_posted`	datetime \| null	Yes	Original posting date, if the platform exposes it.
`valid_through`	datetime \| null	Yes	Expiry date the employer declared, if any.
`qualifications`	object	No	Education, certifications and skills (see Qualifications).
`responsibilities`	string[]	No	Key responsibilities.
`benefits`	string[]	No	Benefits and perks.
`is_work_auth_required`	boolean \| null	Yes	Whether work authorization is required. Null if not mentioned.
`is_h1b_sponsor`	boolean \| null	Yes	Whether H-1B sponsorship is offered. Null if not mentioned.
`is_clearance_required`	boolean \| null	Yes	Whether security clearance is required. Null if not mentioned.

Datetimes are ISO 8601.

Null, empty, and omitted values

Every job carries every key in the table except external_id:

Nullable fields are null, never absent. Handle null on every field marked Yes.
Array fields (locations, responsibilities, benefits) are [] when empty, never null.
external_id is omitted, not null, when unavailable.

Search can drop non-core fields with include_fields (see Shrinking the response). An excluded field keeps its key with an empty value:

Excluded field	Comes back as
`description`	`""`
`summary`	`null`
`responsibilities`, `benefits`	`[]`
`qualifications`	Empty qualification buckets

The feed and GET /api/jobs/{id} always return the full job.

External ID

external_id is the posting’s ID on the platform named by source. It’s returned whenever available, including on searches that request only core fields with include_fields: []. Store it as a string: it can have leading zeros, letters or punctuation. It may differ from the employer’s requisition number and isn’t guaranteed to be globally unique, so keep id as your key for upserts and single-job lookups.

Description format

description is Markdown by default. Jobo converts the employer’s HTML: tags are stripped, line breaks kept, and lists, bold text and links become Markdown (- item, **bold**, [text](url)). Render it as Markdown or show it as plain text. If you render the Markdown to HTML in a web UI, run the output through a sanitizer such as DOMPurify. For HTML, set description_format to html (the default is markdown):

Send it as	On
Query parameter	`GET /api/jobs`, `GET /api/jobs/{id}`, `GET /api/companies/{id}/jobs`
Body field	`POST /api/jobs/search`, `POST /api/jobs/feed`, `POST /api/jobs/feed/managed`, `POST /api/jobs/feed/{feed_id}`

In the HTML, raw HTML from the source is escaped, and only http(s), mailto and relative URLs are kept.

The feed cursor doesn’t carry description_format. Send it with every page, or later pages come back as Markdown.

{
  "cursor": "<next_cursor from the previous page>",
  "description_format": "html"
}

Enums

Responses carry display values (Full-time, On-site, Entry Level), but the employment_type, work_model and experience_level filters accept only the lowercase filter values below. Filtering on a display value matches nothing and returns 200 with total: 0.

Facet buckets are keyed by the filter value, so a facet key works as a filter.
The workplace filter is work_model (work_models in the POST /api/jobs/search and feed bodies); the job field is workplace_type. There is no is_remote parameter or field.
A filter on one of these fields leaves out jobs where the field is null. The feed’s exclude_employment_types, exclude_work_models and exclude_experience_levels are the exception: they keep jobs whose value is unknown.

Employment type

You receive	Filter value	Meaning
`Full-time`	`full-time`	Standard full-time position.
`Part-time`	`part-time`	Part-time position.
`Contract`	`contract`	Contract or contractor engagement.
`Internship`	`internship`	Internship position.
`Freelance`	`freelance`	Freelance or self-employed engagement.
`Temporary`	`temporary`	Temporary or seasonal position.

Workplace type

You receive	Filter value (`work_model`)	Meaning
`Remote`	`remote`	Fully remote position.
`Hybrid`	`hybrid`	Mix of remote and in-office.
`On-site`	`onsite`	Fully in-office or on-site.

Experience level

You receive	Filter value	Meaning
`Intern`	`intern`	Internship, apprenticeship, or co-op.
`Entry Level`	`entry`	Entry-level, junior, associate, or new grad.
`Mid Level`	`mid`	Mid-level or intermediate position.
`Senior`	`senior`	Senior, staff, or principal individual contributor.
`Lead`	`lead`	Team lead, tech lead, or engineering manager.
`Executive`	`executive`	Director, VP, C-level, or other executive.

Source

source is the provider_id of the platform the posting came from, one of 200+ listed on Source platforms. Unlike the enums, the value is the same on input and output: pass it to the sources filter, and facets.sources buckets use it. New platforms are added regularly, so treat the set as open. Don’t hard-code it as a closed enum.

Nested objects

Company

A slim preview of the employer. For the full profile, follow details_url or call GET /api/companies/{id}, which returns the company object.

{
  "id": "b5e6f7a8-1234-5678-9abc-def012345678",
  "name": "Acme Corp",
  "website": "https://acme.com",
  "logo_url": "https://images.jobo.world/logos/companies/0d2c7b9e-1f3a-4c5d-9e8f-7a6b5c4d3e2f.png",
  "summary": "Leading technology company specializing in cloud infrastructure",
  "industries": ["Cloud Infrastructure", "Developer Tools"],
  "categories": ["b2b", "saas"],
  "linkedin_url": "https://www.linkedin.com/company/acme-corp",
  "crunchbase_url": "https://www.crunchbase.com/organization/acme-corp",
  "details_url": "https://connect.jobo.world/api/companies/b5e6f7a8-1234-5678-9abc-def012345678"
}

Field	Type	Nullable	Description
`id`	uuid	No	Unique company identifier.
`name`	string	No	Company display name.
`website`	string \| null	Yes	Company website URL.
`logo_url`	string \| null	Yes	URL of the company logo image.
`summary`	string \| null	Yes	Brief company description.
`industries`	string[]	No	Industry tags, typically 1–3.
`categories`	string[]	No	Business-model tags such as `b2b` or `saas` (all values).
`linkedin_url`	string \| null	Yes	Company LinkedIn profile URL.
`crunchbase_url`	string \| null	Yes	Company Crunchbase profile URL.
`details_url`	string \| null	Yes	URL of the full profile (`GET /api/companies/{id}`). Null only when `id` is empty.

Location

{
  "location": "San Francisco, CA",
  "city": "San Francisco",
  "region": "California",
  "country": "United States",
  "latitude": 37.7749,
  "longitude": -122.4194
}

Field	Type	Nullable	Description
`location`	string \| null	Yes	Raw location string as the employer posted it.
`city`	string \| null	Yes	City name.
`region`	string \| null	Yes	State, province, or region.
`country`	string \| null	Yes	Country name.
`latitude`	number \| null	Yes	Latitude in decimal degrees, when geocoding succeeded.
`longitude`	number \| null	Yes	Longitude in decimal degrees, when geocoding succeeded.

Compensation

{
  "min": 150000,
  "max": 200000,
  "currency": "USD",
  "period": "yearly"
}

Field	Type	Nullable	Description
`min`	number \| null	Yes	Minimum amount.
`max`	number \| null	Yes	Maximum amount.
`currency`	string \| null	Yes	ISO 4217 currency code.
`period`	string \| null	Yes	`yearly`, `monthly`, `weekly`, `daily`, `hourly` or `per-diem`.

Amounts are as the employer published them. Salary filters compare a USD-annualized value that Jobo derives from them; that value isn’t returned.

Occupation

{
  "id": "esco:f2b15a0e-e65a-438a-affb-29b9d50b77d1",
  "name": "Software Engineer",
  "category": "Technology",
  "subcategory": "Software Engineering",
  "isco_code": "2512",
  "onet_soc_codes": ["15-1252.00"]
}

Field	Type	Nullable	Description
`id`	string	No	`esco:<uuid>` for an ESCO occupation, `jobo:<slug>` for one Jobo added. Stable: filter and store on this.
`name`	string	No	Display name, e.g. `Registered Nurse`. Names can improve over time; the `id` doesn’t change.
`category`	string	No	Top level, e.g. `Healthcare`.
`subcategory`	string	No	Second level, e.g. `Nursing`.
`isco_code`	string \| null	Yes	ISCO-08 unit group, e.g. `2221`.
`onet_soc_codes`	string[]	No	O*NET-SOC 2019 codes (see below).

A job has at most one occupation, and occupation is null when the job isn’t classified. It describes the kind of work, not the posting: the employer’s title stays in title and normalized_title, and seniority in experience_level. “Senior Backend Engineer” and “Backend Engineer II” get the same occupation. onet_soc_codes usually holds one code, several where O*NET splits the occupation, and [] when O*NET has no equivalent (as for jobo: occupations). The first seven characters of a code are its SOC 2018 code: 15-1252.00 is SOC 15-1252. Search and POST /api/jobs/feed filter on the taxonomy:

Filter	Matches	Example
`job_categories`	`category`, ignoring case	`Healthcare`
`job_subcategories`	`subcategory`, ignoring case	`Nursing`
`occupation_ids`	`id`	`esco:f2b15a0e-e65a-438a-affb-29b9d50b77d1`

GET /api/occupations lists every category, subcategory and occupation; Search recipes has examples. Occupations come from the ESCO classification and O*NET-SOC codes from the O*NET database; see Open data licenses and attribution.

Qualifications

{
  "must_have": {
    "education": ["Bachelor's in Computer Science or equivalent"],
    "certifications": [],
    "skills": [
      { "name": "Python", "type": "hard" },
      { "name": "Kubernetes", "type": "hard" }
    ]
  },
  "preferred": {
    "education": [],
    "certifications": [],
    "skills": [
      { "name": "Terraform", "type": "hard" },
      { "name": "Leadership", "type": "soft" }
    ]
  }
}

qualifications always has two buckets, must_have and preferred, each with these fields:

Field	Type	Nullable	Description
`education`	string[]	No	Education requirements.
`certifications`	string[]	No	Certifications.
`skills`	object[]	No	Skills, each with `name` (string) and `type` (`"hard"` or `"soft"`).

Skill type

Value	Description
`hard`	Technical skills: technologies, tools, frameworks, programming languages.
`soft`	Interpersonal, behavioral, and cognitive skills.

Complete example

A fully populated job object:

{
  "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "external_id": "4567890",
  "title": "Senior Software Engineer",
  "normalized_title": "software_engineer",
  "occupation": {
    "id": "esco:f2b15a0e-e65a-438a-affb-29b9d50b77d1",
    "name": "Software Engineer",
    "category": "Technology",
    "subcategory": "Software Engineering",
    "isco_code": "2512",
    "onet_soc_codes": ["15-1252.00"]
  },
  "company": {
    "id": "b5e6f7a8-1234-5678-9abc-def012345678",
    "name": "Acme Corp",
    "website": "https://acme.com",
    "logo_url": "https://images.jobo.world/logos/companies/0d2c7b9e-1f3a-4c5d-9e8f-7a6b5c4d3e2f.png",
    "summary": "Leading technology company specializing in cloud infrastructure",
    "industries": ["Cloud Infrastructure", "Developer Tools"],
    "categories": ["b2b", "saas"],
    "linkedin_url": "https://www.linkedin.com/company/acme-corp",
    "crunchbase_url": "https://www.crunchbase.com/organization/acme-corp",
    "details_url": "https://connect.jobo.world/api/companies/b5e6f7a8-1234-5678-9abc-def012345678"
  },
  "description": "We are looking for a **Senior Software Engineer** to join our platform team.\n\n- Design and build scalable microservices\n- Mentor junior engineers\n- Collaborate with product and design teams\n\nYou'll work on systems that serve millions of requests per day.",
  "language": "en",
  "summary": "Senior Software Engineer role at Acme Corp focused on building scalable microservices, mentoring junior engineers, and collaborating cross-functionally on high-traffic platform systems.",
  "listing_url": "https://boards.greenhouse.io/acmecorp/jobs/4567890",
  "apply_url": "https://boards.greenhouse.io/acmecorp/jobs/4567890#app",
  "locations": [
    {
      "location": "San Francisco, CA",
      "city": "San Francisco",
      "region": "California",
      "country": "United States",
      "latitude": 37.7749,
      "longitude": -122.4194
    },
    {
      "location": "Remote",
      "city": null,
      "region": null,
      "country": "United States",
      "latitude": null,
      "longitude": null
    }
  ],
  "compensation": {
    "min": 150000,
    "max": 200000,
    "currency": "USD",
    "period": "yearly"
  },
  "employment_type": "Full-time",
  "workplace_type": "Hybrid",
  "experience_level": "Senior",
  "source": "greenhouse",
  "created_at": "2026-02-16T08:30:00Z",
  "updated_at": "2026-02-28T14:15:00Z",
  "date_posted": "2026-02-15T00:00:00Z",
  "valid_through": "2026-04-15T00:00:00Z",
  "qualifications": {
    "must_have": {
      "education": ["Bachelor's in Computer Science or equivalent"],
      "certifications": [],
      "skills": [
        { "name": "Python", "type": "hard" },
        { "name": "Kubernetes", "type": "hard" },
        { "name": "PostgreSQL", "type": "hard" },
        { "name": "REST APIs", "type": "hard" }
      ]
    },
    "preferred": {
      "education": ["Master's in Computer Science"],
      "certifications": ["AWS Solutions Architect"],
      "skills": [
        { "name": "Terraform", "type": "hard" },
        { "name": "Go", "type": "hard" },
        { "name": "Leadership", "type": "soft" },
        { "name": "Technical Writing", "type": "soft" }
      ]
    }
  },
  "responsibilities": [
    "Design and build scalable microservices using Python and Go",
    "Lead code reviews and establish engineering best practices",
    "Mentor junior and mid-level engineers",
    "Collaborate with product managers to define technical requirements",
    "Participate in on-call rotation for production systems"
  ],
  "benefits": [
    "Competitive salary with equity",
    "Unlimited PTO",
    "Health, dental, and vision insurance",
    "401(k) with 4% company match",
    "Annual learning & development budget ($5,000)",
    "Home office stipend"
  ],
  "is_work_auth_required": true,
  "is_h1b_sponsor": true,
  "is_clearance_required": false
}

Returned by

GET /api/jobs and POST /api/jobs/search, in the jobs array
GET /api/jobs/{id}, as the whole response body
GET /api/companies/{id}/jobs, in the jobs array
POST /api/jobs/feed, POST /api/jobs/feed/managed and POST /api/jobs/feed/{feed_id}, in the jobs array

Overview

Conventions

Jobs

Feed

Companies

Locations

Auto Apply

Fields

Null, empty, and omitted values

External ID

Description format

Enums

Employment type

Workplace type

Experience level

Source

Nested objects

Company

Location

Compensation

Occupation

Qualifications

Skill type

Complete example

Returned by

​Fields

​Null, empty, and omitted values

​External ID

​Description format

​Enums

​Employment type

​Workplace type

​Experience level

​Source

​Nested objects

​Company

​Location

​Compensation

​Occupation

​Qualifications

​Skill type

​Complete example

​Returned by

Fields

Null, empty, and omitted values

External ID

Description format

Enums

Employment type

Workplace type

Experience level

Source

Nested objects

Company

Location

Compensation

Occupation

Qualifications

Skill type

Complete example

Returned by