> ## Documentation Index
> Fetch the complete documentation index at: https://jobo.world/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Job Object Schema

> Complete reference for the Job object returned by all API endpoints.

## 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 canonical title in snake\_case, e.g. `software_engineer` (null if unavailable) |
| `company`               | object           | No       | Employer information (see [Company](#company))                                            |
| `description`           | string           | No       | Cleaned job description (HTML — see [note below](#html-in-descriptions))                  |
| `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](#location)), empty array if unspecified            |
| `compensation`          | object \| null   | Yes      | Salary/compensation details (null if not disclosed — see [Compensation](#compensation))   |
| `employment_type`       | string \| null   | Yes      | Employment type (see [Employment Type](#employment-type))                                 |
| `workplace_type`        | string \| null   | Yes      | Workplace arrangement (see [Workplace Type](#workplace-type))                             |
| `experience_level`      | string \| null   | Yes      | Seniority level (see [Experience Level](#experience-level))                               |
| `source`                | string           | No       | ATS platform identifier (see [Source](#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.                                  |
| `qualifications`        | object           | No       | Structured qualifications (see [Qualifications](#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

<Warning>
  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](https://github.com/cure53/DOMPurify) as an additional safety layer.
</Warning>

## Enum Fields

### Employment Type

| Value        | Description                          |
| ------------ | ------------------------------------ |
| `Full-time`  | Standard full-time position          |
| `Part-time`  | Part-time position                   |
| `Contract`   | Contract or contractor engagement    |
| `Internship` | Internship position                  |
| `Freelance`  | Freelance / self-employed engagement |
| `Temporary`  | Temporary or seasonal position       |

### Workplace Type

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

### Experience Level

| Value         | Description                                        |
| ------------- | -------------------------------------------------- |
| `Intern`      | Internship, apprenticeship, or co-op               |
| `Entry Level` | Entry-level / junior / associate / new grad        |
| `Mid Level`   | Mid-level or intermediate position                 |
| `Senior`      | Senior, staff, or principal individual contributor |
| `Lead`        | Team lead, tech lead, or engineering manager       |
| `Executive`   | Director, VP, C-level, or other executive          |

### 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`, `dover`, `hibob`, `hirebridge`, `hireology`, `manatal`, `pageup`, `paycor`, `rival`, `trinet`, `werecruit`

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

```json theme={null}
{
  "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",
  "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 to company logo image                                                                  |
| `summary`        | string \| null | Yes      | Brief company description                                                                  |
| `industries`     | string\[]      | No       | Industry tags (typically 1–3). Empty array when unknown.                                   |
| `categories`     | string\[]      | No       | Business-model bucket tags (`b2b`, `b2c`, `saas`, `service-provider`). Empty when unknown. |
| `linkedin_url`   | string \| null | Yes      | Company LinkedIn profile URL                                                               |
| `crunchbase_url` | string \| null | Yes      | Company Crunchbase profile URL                                                             |
| `details_url`    | string \| null | Yes      | URL to the full company profile endpoint (`GET /api/companies/{id}`). Null if `id` empty.  |

### Location

```json theme={null}
{
  "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

```json theme={null}
{
  "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 |
| `weekly`   | Weekly rate    |
| `daily`    | Daily rate     |
| `hourly`   | Hourly rate    |
| `per-diem` | Per-diem rate  |

### Qualifications

```json theme={null}
{
  "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:

```json theme={null}
{
  "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",
    "industries": ["Cloud Infrastructure", "Developer Tools"],
    "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": "<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",
  "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
}
```

<Note>
  **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.
</Note>