API DOCUMENTATION / JOB AND POSTING FIELDS
Job and posting fields
Understand combined job IDs, posting IDs, state-bearing values, and the difference between list and detail DTOs.
Combined job and posting identities
| Field | Meaning |
|---|---|
job_id | UUID for a combined job record in the public projection. |
postings[].posting_id | Identifier for one posting associated with the combined job. |
postings[].source_posting_id | Identifier supplied by the underlying source. |
company_id | Nullable canonical company UUID; it is not an employer domain or discovery key. |
Five field-state envelopes
| State | Serialized shape | Meaning |
|---|---|---|
known | {"state":"known","value":"Engineer"} | A value is available. |
source_omitted | {"state":"source_omitted"} | The source did not provide this value; there is no value key. |
source_unmapped | {"state":"source_unmapped","value":null,"evidence":["source label"]} | Evidence exists, but no normalized value was mapped. Here value is explicitly null. |
extraction_failed | {"state":"extraction_failed"} | Extraction did not produce a value; there is no value key. |
derived | {"state":"derived","value":"hybrid","evidence":["source text"]} | A derived value includes its evidence. |
These states are not interchangeable with a nullable field. The public serializer does not emit the internal inferred state.
Job-level fields
The inspected job DTO includes job_id, currentness, stale, nullable company_id, state-bearing employer_name, title, description, and work_arrangement, a locations array, and timestamps job_first_seen_at, curated_at, and job_updated_at.
Posting-level fields
Postings include posting_id, source board ID, source_posting_id, posting_status, posting/application URL, location and pay values, nullable source_posted_at, first_seen_at, nullable last_completed_fetch_at, and nullable latest_application_check. Detail also serializes attribution. The complete list example on the getting-started page shows one posting with omitted source values.
The list and detail responses differ
| Behavior | Jobs list | Job detail |
|---|---|---|
| Company include | include=company can add a company object or null. | include=company can add a company object or null. |
| Attribution | Not included by the list serializer. | Included on each posting. |
| Source data | With include=source_data, stored source_data and source_rights pass through. | Optional source_data is normalized to named snake_case properties. |
| Description format | HTML format request can return 503 until confirmed source HTML is available. | HTML format request can return 503 until confirmed source HTML is available. |
Posting attribution in detail
{"required":null,"text":null,"link":null}Every detail posting includes attribution with nullable required, text, and link. The list serializer omits this object.
Not every source value becomes a normalized field
Benefits, hours, education or experience requirements, skills, responsibilities, qualifications, and hiring-team contacts are not separate normalized fields in this DTO. Optional posting source_data preserves source-dependent values; list and detail representations differ.
Continue in the reference
Check related request behavior before you build.
View route status and methods Discuss API requirements