Schemas

Download schema

Error

Error body of every error this API raises itself.

error

string · required

Human-readable error message.

ValidationError

Framework validation error, returned with `422` when a parameter has the wrong type, is missing, or is out of range.

object[] · required

JobPage

One page of jobs, shared by list and search.

Job[] · required

The jobs on this page, ordered by id ascending.

has_more

boolean · required

true if at least one more job follows this page.

next_cursor

string | null · required

Pass as cursor to get the next page. null when has_more is false.

Job

One job posting. Every field is always present; a value that is not known is `null`. A source that published an empty value can reach you as an empty string (or a list holding one), so treat `""` like `null`. Field names follow the widely used fantastic.jobs vocabulary. Despite the `ai_` prefix, the employment-type, work-arrangement and salary fields are taken from the posting, not generated by a model. Fields ending in `_derived` are lists with one element, or `null` — except `domain_derived`, which is a plain string.

id

integer · int64 · required

Job id. Stable; use it for GET /v1/jobs/{job_id} and for de-duplication.

title

string · required

Job title as posted.

organization

string · required

Name of the hiring company.

url

string · uri · required

Link to the original posting on the company's applicant tracking system.

date_posted

string | null · date-time · required

When the posting says it was published (ISO 8601 with UTC offset).

date_created

string | null · date-time · required

When we first recorded the job (ISO 8601 with UTC offset). Can be earlier than date_posted if the employer re-dated the posting.

date_valid_through

string | null · date-time · required

Closing date, if the posting gives one (ISO 8601 with UTC offset).

source_type

string · const · required

Always ats — every job comes from an applicant tracking system.

Const value: ats

source

string | null · required

Short name of the applicant tracking system the job was collected from.

source_domain

string | null · required

Host the posting is served from, without www.. Only set when source is known.

domain_derived

string | null · required

The hiring company's own web domain, when known.

locations_derived

array | null · required

Display location as City, State, Country (parts that are not known are left out).

cities_derived

array | null · required

City.

regions_derived

array | null · required

State or province.

countries_derived

array | null · required

Country name (an ISO 3166-1 alpha-2 code when the name is not known).

timezones_derived

array | null · required

IANA time zone of the city.

lats_derived

array | null · required

Latitude of the city.

lngs_derived

array | null · required

Longitude of the city.

employment_type

array | null · required

Employment type as posted.

Enum values:

FULL_TIME

PART_TIME

CONTRACTOR

INTERN

TEMPORARY

VOLUNTEER

OTHER

ai_employment_type

array | null · required

Same value as employment_type (kept for compatibility with the fantastic.jobs format).

Enum values:

FULL_TIME

PART_TIME

CONTRACTOR

INTERN

TEMPORARY

VOLUNTEER

OTHER

ai_work_arrangement

string | null · enum · required

Work arrangement as posted. null when the posting does not state it clearly.

Enum values:

On-site

Hybrid

Remote Solely

ai_salary_currency

string | null · required

Salary currency as posted, e.g. USD.

ai_salary_min_value

number | null · required

Lower salary bound as posted. Never converted or annualised.

ai_salary_max_value

number | null · required

Upper salary bound as posted. Never converted or annualised.

ai_salary_unit_text

string | null · enum · required

Period the salary values refer to. null when unknown or for other periods (for example daily).

Enum values:

HOUR

WEEK

MONTH

YEAR