Job Object Schema

Job Object

Every API endpoint that returns jobs uses this unified schema.

Field	Type	Nullable	Description
`id`	uuid	No	Unique job identifier
`title`	string	No	Job title as listed
`normalized_title`	string \| null	Yes	Normalized standard title (null if normalization not available)
`company`	object	No	Employer information (see Company)
`description`	string	No	Cleaned job description (HTML — see note below)
`summary`	string \| null	Yes	AI-generated summary (null for recently indexed jobs pending summarization)
`listing_url`	string	No	Direct URL to original posting
`apply_url`	string	No	Deep link to application form
`locations`	object[]	No	Array of job locations (see Location), empty array if unspecified
`compensation`	object \| null	Yes	Salary/compensation details (null if not disclosed — see Compensation)
`employment_type`	string \| null	Yes	Employment type (see Employment Type)
`workplace_type`	string \| null	Yes	Workplace arrangement (see Workplace Type)
`experience_level`	string \| null	Yes	Seniority level (see Experience Level)
`source`	string	No	ATS platform identifier (see Source)
`created_at`	datetime	No	When first indexed by Jobo (ISO 8601)
`updated_at`	datetime	No	Last update time (ISO 8601)
`date_posted`	datetime \| null	Yes	Original posting date (ISO 8601). Null if the ATS doesn’t expose it.
`valid_through`	datetime \| null	Yes	Listing validity/expiry date. Null if no expiration set.
`is_remote`	boolean	No	True if remote work offered
`qualifications`	object	No	Structured qualifications (see Qualifications)
`responsibilities`	string[]	No	Key responsibilities (empty array if not extracted)
`benefits`	string[]	No	Benefits and perks (empty array if not extracted)
`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)

HTML in Descriptions

The description field contains sanitized HTML (not plain text). Common tags include <p>, <ul>, <li>, <strong>, <em>, <br>, and <h3>. All potentially dangerous tags (e.g., <script>, <iframe>) are stripped during ingestion. If you’re rendering descriptions in a web UI, use an HTML sanitizer like DOMPurify as an additional safety layer.

Enum Fields

Employment Type

Value	Description
`Full-time`	Standard full-time position
`Part-time`	Part-time position
`Contract`	Contract or freelance work
`Internship`	Internship position
`Temporary`	Temporary position

Workplace Type

Value	Description
`Remote`	Fully remote position
`Hybrid`	Mix of remote and in-office
`Onsite`	Fully in-office/on-site

Experience Level

Value	Description
`Entry Level`	Entry-level or junior position
`Mid Level`	Mid-level or intermediate position
`Senior Level`	Senior position
`Lead/Staff`	Lead or staff-level position
`Principal`	Principal engineer/role
`Director`	Director-level position
`VP`	Vice president level
`Executive`	C-level or executive position

Source

The source field identifies the ATS (Applicant Tracking System) platform the job was scraped from. Examples include: greenhouse, lever, workday, ashby, bamboohr, icims, smartrecruiters, teamtailor, workable, rippling, personio, taleo, successfactors, paylocity, dayforce, phenompeople, jobvite, eightfold, jazzhr, breezy, recruitee, applicantpro, comeet, pinpoint, freshteam, gem, polymer, kula, homerun, careerplug, joincom, recooty, trakstar, hirehive, hiringthing, zohorecruit, gohire, jobscore, csod, adpmyjobs, adpworkforcenow, paycom, ultipro, isolved, oraclecloud, talnet, careerpuck New sources are added as we expand coverage. Use the value as an opaque identifier — do not hard-code assumptions about the set of possible values.

Nested Objects

Company

{
  "id": "b5e6f7a8-1234-5678-9abc-def012345678",
  "name": "Acme Corp",
  "website": "https://acme.com",
  "logo_url": "https://logo.clearbit.com/acme.com",
  "summary": "Leading technology company specializing in cloud infrastructure"
}

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 to company logo image
`summary`	string \| null	Yes	Brief company description

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 parsed
`city`	string \| null	Yes	City name
`region`	string \| null	Yes	State/province/region
`country`	string \| null	Yes	Country name
`latitude`	number \| null	Yes	Latitude coordinate
`longitude`	number \| null	Yes	Longitude coordinate

Compensation

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

Field	Type	Nullable	Description
`min`	number \| null	Yes	Minimum compensation amount
`max`	number \| null	Yes	Maximum compensation amount
`currency`	string \| null	Yes	ISO 4217 currency code
`period`	string \| null	Yes	Pay period (see below)

Period	Description
`yearly`	Annual salary
`monthly`	Monthly salary
`hourly`	Hourly rate
`weekly`	Weekly rate
`daily`	Daily rate

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" }
    ]
  }
}

The qualifications object contains two buckets — must_have and preferred — each with:

Field	Type	Description
`education`	string[]	Required or preferred education (empty array if none)
`certifications`	string[]	Required or preferred certifications (empty array if none)
`skills`	object[]	Array of skill objects, each with `name` (string) and `type` (`"hard"` or `"soft"`)

Skill Type

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

Complete Example

A fully populated Job object showing all fields:

{
  "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "title": "Senior Software Engineer",
  "normalized_title": "Software Engineer",
  "company": {
    "id": "b5e6f7a8-1234-5678-9abc-def012345678",
    "name": "Acme Corp",
    "website": "https://acme.com",
    "logo_url": "https://logo.clearbit.com/acme.com",
    "summary": "Leading technology company specializing in cloud infrastructure"
  },
  "description": "<p>We are looking for a <strong>Senior Software Engineer</strong> to join our platform team.</p><ul><li>Design and build scalable microservices</li><li>Mentor junior engineers</li><li>Collaborate with product and design teams</li></ul><p>You'll work on systems that serve millions of requests per day.</p>",
  "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 Level",
  "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",
  "is_remote": true,
  "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
}

Nullable fields — Fields marked as nullable in the schema above will be null (not absent) when no data is available. Your application should always handle null values gracefully. Array fields (locations, responsibilities, benefits) will be empty arrays [] rather than null when no data is present.

Getting Started

Resources

Job Object

HTML in Descriptions

Enum Fields

Employment Type

Workplace Type

Experience Level

Source

Nested Objects

Company

Location

Compensation

Qualifications

Skill Type

Complete Example

Getting Started

Resources

​Job Object

​HTML in Descriptions

​Enum Fields

​Employment Type

​Workplace Type

​Experience Level

​Source

​Nested Objects

​Company

​Location

​Compensation

​Qualifications

​Skill Type

​Complete Example

Job Object

HTML in Descriptions

Enum Fields

Employment Type

Workplace Type

Experience Level

Source

Nested Objects

Company

Location

Compensation

Qualifications

Skill Type

Complete Example