# Job

Schemas

Job postings with the title, employer, location and workplace type, employment type, seniority, salary range, description, posting date, whether it is closed, applicants and apply link.

## Endpoints

5 endpoints return jobs on Hacker News and LinkedIn.

- [GETHacker News Who Is Hiring API`/v1/hackernews/whoishiring_jobs`](https://socialtap.dev/docs/reference/hackernews/whoishiring-jobs/index.md)
- [GETLinkedIn Job API`/v1/linkedin/job`](https://socialtap.dev/docs/reference/linkedin/job/index.md)
- [GETLinkedIn Similar Jobs API`/v1/linkedin/job_related_jobs`](https://socialtap.dev/docs/reference/linkedin/job-related-jobs/index.md)
- [GETLinkedIn Company Jobs API`/v1/linkedin/jobs`](https://socialtap.dev/docs/reference/linkedin/jobs/index.md)
- [GETLinkedIn Job Search API`/v1/linkedin/search_jobs`](https://socialtap.dev/docs/reference/linkedin/search-jobs/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (linkedin, …). |
| `id` | `string` | Platform-native job ID (string; LinkedIn's numeric job ID). |
| `url` | `string` (uri) | Canonical job page URL (https://www.linkedin.com/jobs/view/\<id>/). |
| `title` | `string` | The job's title as the employer wrote it. |
| `employer` | `object` or `null` | The company (or person) hiring, as the board names it: its account on the platform when it has one; null when the board does not say who is hiring (a confidential posting, an Upwork client). |
| `employer.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `employer.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `employer.display_name` | `string` or `null` | Display name shown on the profile. |
| `employer.url` | `string` (uri) or `null` | Canonical profile URL. |
| `employer.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `employer.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `description` | `string` or `null` | The full description as plain text, line breaks kept (paragraphs and list items each on their own line); null when the board shows none. |
| `locations` | `object[]` | Where the job is based, the main location first, as the board shows them; \[\] when none is shown (a remote job with no location), listed in unknown_fields when the source cannot see them. |
| `locations[].name` | `string` | The location as the board shows it, one line (San Francisco, CA; London Area, United Kingdom; United States). |
| `locations[].city` | `string` or `null` | City, as shown; null when the location is wider than a city or the board does not give one. |
| `locations[].region` | `string` or `null` | State, province or region, as shown (NY, Ontario); null when not given. |
| `locations[].country_code` | `string` or `null` | ISO 3166-1 alpha-2 country; null when the board does not give one or the location spans several. |
| `workplace_type` | `string` or `null` | Where the work is done: on_site, hybrid (partly remote) or remote; null when the board does not say. New values may be added; treat unknown values as null.<br>One of `on_site`, `hybrid`, `remote` |
| `employment_types` | `string[]` | The terms of employment, in the order the board gives them (a posting may name several: full_time and part_time): full_time, part_time, contract (freelance and contractor roles), temporary (seasonal too), internship, volunteer, other; \[\] when the board does not say (listed in unknown_fields when the source cannot see them). New values may be added; treat unknown values as other.<br>One of `full_time`, `part_time`, `contract`, `temporary`, `internship`, `volunteer`, `other` |
| `seniority` | `string` or `null` | The experience level asked for, as the board labels it (Entry level, Mid-Senior level, Expert; not normalized: each board has its own scale); null when not stated. |
| `salary` | `object` or `null` | The pay stated for the job; null when none is stated. |
| `salary.min` | `number` or `null` | Lowest pay of the range, in major units of currency per period; equal to max for a single figure; null when only a maximum is stated ("up to $90,000"). |
| `salary.max` | `number` or `null` | Highest pay of the range, in major units of currency per period; equal to min for a single figure; null when only a minimum is stated ("from $40/hr"). |
| `salary.currency` | `string` | ISO 4217 code of both amounts (USD). |
| `salary.period` | `string` or `null` | What one amount pays for: an hour, day, week, month or year of work, or total (a fixed price for the whole job, as an Upwork fixed-price budget); null when the board does not say. New values may be added; treat unknown values as null.<br>One of `hour`, `day`, `week`, `month`, `year`, `total` |
| `salary.is_estimated` | `boolean` or `null` | The board estimated the pay itself rather than the employer stating it; false when the employer stated it; null when the board does not say. |
| `industries` | `string[]` | The industries the board files the job under, as shown (not normalized), the main one first; \[\] when none is shown. |
| `job_functions` | `string[]` | The kinds of work the board files the job under (Engineering, Sales), as shown (not normalized); \[\] when none is shown. |
| `skills` | `string[]` | Skills the posting asks for, as the board tags them; \[\] when none (listed in unknown_fields when the source cannot see them). |
| `benefits` | `string[]` | Benefits the posting lists (Health insurance, 401(k)), as shown; \[\] when none (listed in unknown_fields when the source cannot see them). |
| `published_at` | `string` (date-time) or `null` | When the job was posted (its latest listing when reposted), RFC 3339 UTC; a date or relative label ("2 weeks ago") is listed in approximate_fields; null when not shown. |
| `expires_at` | `string` (date-time) or `null` | When the posting is set to close, RFC 3339 UTC; null when the board shows no end. |
| `is_closed` | `boolean` or `null` | The job no longer accepts applications, as the board says at fetch time; false when it still does; null when the board does not say. |
| `is_easy_apply` | `boolean` or `null` | Applied for on the platform itself (LinkedIn's and Glassdoor's Easy Apply, Indeed Apply, an Upwork proposal); false when the application is on the employer's site (apply_url); null when not shown. |
| `apply_url` | `string` (uri) or `null` | The employer's application page, for a job applied for off the platform (is_easy_apply false); null for one applied for on the platform, or when the board does not show the link. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.applicant_count` | `integer` or `null` | People who applied, as the board counts them (a bucket such as "Over 200 applicants" gives its bound, listed in approximate_fields); null when not shown. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.linkedin` | `object` or `null` | A LinkedIn job's own fields. |
| `platform_specific.linkedin.title_id` | `string` or `null` | ID of the standardized title LinkedIn files the job under (9: Software Engineer), as its job search's f_T filter takes it; null when not shown. |
| `platform_specific.linkedin.industry_ids` | `string[]` | IDs of the industries LinkedIn files the job under (43: Financial Services), as its job search's f_I filter takes them, in the order of industries; \[\] when none is shown (listed in unknown_fields when the source cannot see them). |
| `platform_specific.linkedin.hiring_team` | `object[]` | The members LinkedIn names as hiring for the job (the recruiter or hiring manager who posted it), the poster first; \[\] when none is shown (listed in unknown_fields when the source cannot see them). |
| `platform_specific.linkedin.hiring_team[].id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `platform_specific.linkedin.hiring_team[].username` | `string` or `null` | Handle without the @; null when the account has none. |
| `platform_specific.linkedin.hiring_team[].display_name` | `string` or `null` | Display name shown on the profile. |
| `platform_specific.linkedin.hiring_team[].url` | `string` (uri) or `null` | Canonical profile URL. |
| `platform_specific.linkedin.hiring_team[].avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `platform_specific.linkedin.hiring_team[].is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `platform_specific.hackernews` | `object` or `null` | A Hacker News job's own fields. |
| `platform_specific.hackernews.poster` | `object` or `null` | The Hacker News account that posted the job: often a founder, a hiring manager or a recruiter at the company. |
| `platform_specific.hackernews.poster.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `platform_specific.hackernews.poster.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `platform_specific.hackernews.poster.display_name` | `string` or `null` | Display name shown on the profile. |
| `platform_specific.hackernews.poster.url` | `string` (uri) or `null` | Canonical profile URL. |
| `platform_specific.hackernews.poster.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `platform_specific.hackernews.poster.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `platform_specific.hackernews.thread` | `object` or `null` | The monthly Who is hiring thread the job was posted in. |
| `platform_specific.hackernews.thread.id` | `string` | The thread's item ID. |
| `platform_specific.hackernews.thread.title` | `string` or `null` | The thread's title (Ask HN: Who is hiring? (November 2026)). |
| `platform_specific.hackernews.thread.url` | `string` (uri) | The thread's page on Hacker News. |
| `platform_specific.hackernews.header` | `string` or `null` | The job's first line as the poster wrote it (Company \| Role \| Location \| REMOTE \| Full-time \| salary, by the thread's convention), from which title, employer, locations, workplace_type, employment_types and salary are read. |
| `platform_specific.hackernews.is_visa_sponsored` | `boolean` or `null` | The first line says the job sponsors a visa (VISA, visa sponsorship); false when it says it doesn't; null when it says neither. |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text ("Over 200 applicants": metrics.applicant_count; "2 weeks ago": published_at). \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, job endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/job/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)
