> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/job-postings/openapi.json](/docs/api/job-postings/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Job postings

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

Search job postings, read one with its history and export the results.

Prospecting data. 5 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/job-postings/openapi.json](/docs/api/job-postings/openapi.json).

- `GET /v1/job-postings/{jobPostingId}` - Get a job posting (`job-postings.get`): [/docs/api/job-postings/get.md](/docs/api/job-postings/get.md)
- `POST /v1/job-postings/search` - Search job postings (`job-postings.search`): [/docs/api/job-postings/search.md](/docs/api/job-postings/search.md)
- `POST /v1/job-postings/search/export` - Export job postings (`job-postings.export`): [/docs/api/job-postings/export.md](/docs/api/job-postings/export.md)
- `GET /v1/job-postings/export-allowance` - Get the job posting export allowance (`job-postings.get-export-allowance`): [/docs/api/job-postings/get-export-allowance.md](/docs/api/job-postings/get-export-allowance.md)
- `POST /v1/job-postings/filters/resolve` - Resolve job filter values (`job-postings.resolve-filters`): [/docs/api/job-postings/resolve-filters.md](/docs/api/job-postings/resolve-filters.md)

## Get a job posting

`GET /v1/job-postings/{jobPostingId}` - operationId `job-postings.get`

| Permission | Rate limit |
| --- | --- |
| Search view | 12,000 requests a minute per API key |

Get one job posting with the source document Kenso read it from and its earlier revisions.

A posting stays readable after it closes. The call is free and does not use the export allowance.

Errors:

- `402 plan_required`: the workspace's plan does not include job post search. `error.refusal` carries
the code `PLAN_FEATURE_NOT_AVAILABLE` and the feature `job_post_search`.
- `404 not_found`: no posting has this id.
- `503 service_unavailable`: job postings are not available right now. Try again.
- `504 upstream_timeout`: job postings took too long to answer. Try again.

Requires Search view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/job-postings/GET/v1/job-postings/%7BjobPostingId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `jobPostingId` | path | string | yes | The posting's id from a search result: up to 64 letters, digits, `_` or `-`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `JobPostingDetail`.

| Field | Type | Description |
| --- | --- | --- |
| `job` | JobPosting | The posting, with its description and company. |
| `raw` | map of object | The posting's current source document, as its source published it. Its fields depend on the source. |
| `raw_detail` | map of object | The source's detail document for the posting, whose fields depend on the source. Null when the source has none. |
| `revisions` | array of JobPostingRevision | The versions of the posting Kenso saved, newest first. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/job-postings/01JC8Z3K6Q2W4M7N9P5R1T3V5X" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "job": {
      "id": "string",
      "title": "string",
      "description": "string",
      "description_html": "string",
      "company": {
        "id": "string",
        "name": "string",
        "domain": "acme.com",
        "website_url": "https://example.com",
        "linkedin_url": "https://example.com",
        "ken_search_id": "string"
      },
      "company_name": "string",
      "company_domain": "acme.com",
      "location": "string",
      "locations": [
        "string"
      ],
      "country": "string",
      "remote": true,
      "workplace_type": "string",
      "department": "string",
      "team": "string",
      "employment_type": "string",
      "seniority": "string",
      "language": "string",
      "salary_raw": "string",
      "salary_currency": "USD",
      "salary_min": 0.5,
      "salary_max": 0.5,
      "salary_min_usd": 0.5,
      "salary_max_usd": 0.5,
      "equity": "string",
      "requisition_id": "string",
      "tags": [
        "string"
      ],
      "is_agency": true,
      "source": "string",
      "source_url": "https://example.com",
      "application_url": "https://example.com",
      "status": "string",
      "posted_at": "2026-09-23T15:02:11Z",
      "first_seen_at": "2026-09-23T15:02:11Z",
      "last_seen_at": "2026-09-23T15:02:11Z",
      "closed_at": "2026-09-23T15:02:11Z",
      "expires_at": "2026-09-23T15:02:11Z"
    },
    "raw": {
      "key": null
    },
    "raw_detail": {
      "key": null
    },
    "revisions": [
      {
        "fetched_at": "2026-09-23T15:02:11Z",
        "title": "string",
        "location": "string",
        "salary_raw": "string",
        "description": "string",
        "description_html": "string",
        "raw": {
          "key": null
        }
      }
    ]
  }
}
```

## Search job postings

`POST /v1/job-postings/search` - operationId `job-postings.search`

| Permission | Rate limit |
| --- | --- |
| Search view | 240 requests a minute per API key |

Search job postings with filters and get one page of postings. Use it to find companies that are hiring for a
role, in a place or on a date range.

Send at least one filter, for example `titles`, `location`, `hasRemote`, `postedWithin` (days)
or `status` (`open` by default, `closed` or `all`). `limit` sets the page size, from 1 to
50, and `cursor` takes the previous page's `pagination.next_cursor`. `groupBy: "company"` returns
one row per company. Request fields are camelCase, and the postings come back with snake_case fields such as
`posted_at`.

The search is free and does not use the export allowance.

Errors:

- `400 validation_failed`: a filter or `limit` is not valid.
- `402 plan_required`: the workspace's plan does not include job post search. `error.refusal` carries
the code `PLAN_FEATURE_NOT_AVAILABLE` and the feature `job_post_search`.
- `413 validation_failed`: the body is larger than 1 MB.
- `422 filter_required`: the body sets no filter.
- `503 service_unavailable`: job postings are not available right now. Try again.
- `504 upstream_timeout`: job postings took too long to answer. Try again.

Requires Search view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/job-postings/POST/v1/job-postings/search)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `JobPostingSearchPage`.

| Field | Type | Description |
| --- | --- | --- |
| `signals` | array of JobPosting | The postings on this page, newest posted first. Present unless the search sets `groupBy` to `company`. |
| `companies` | array of JobPostingCompanyGroup | The hiring companies on this page, most matching postings first. Present only when `groupBy` is `company`. |
| `total` | integer (int64) | The postings that match across all pages, or the companies with `groupBy: "company"`. It stops at 1,000 when `totalMode` is `capped`, and is null when `totalMode` is `none`. |
| `totalMode` | string | How `total` was counted: `capped` (the default), `exact` or `none`. |
| `notes` | array of string | Notes about the answer, for example `total capped at 1000` when more postings match than `total` says. |
| `pagination` | JobPostingPagination | How to get the next page. |
| `facets` | JobPostingFacets | The matching postings counted by source, country, seniority, remote and status. Present only with `includeFacets: true`. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/job-postings/search" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "signals": [
      {
        "id": "string",
        "title": "string",
        "description": "string",
        "description_html": "string",
        "company": {
          "id": "string",
          "name": "string",
          "domain": "acme.com",
          "website_url": "https://example.com",
          "linkedin_url": "https://example.com",
          "ken_search_id": "string"
        },
        "company_name": "string",
        "company_domain": "acme.com",
        "location": "string",
        "locations": [
          "string"
        ],
        "country": "string",
        "remote": true,
        "workplace_type": "string",
        "department": "string",
        "team": "string",
        "employment_type": "string",
        "seniority": "string",
        "language": "string",
        "salary_raw": "string",
        "salary_currency": "USD",
        "salary_min": 0.5,
        "salary_max": 0.5,
        "salary_min_usd": 0.5,
        "salary_max_usd": 0.5,
        "equity": "string",
        "requisition_id": "string",
        "tags": [
          "string"
        ],
        "is_agency": true,
        "source": "string",
        "source_url": "https://example.com",
        "application_url": "https://example.com",
        "status": "string",
        "posted_at": "2026-09-23T15:02:11Z",
        "first_seen_at": "2026-09-23T15:02:11Z",
        "last_seen_at": "2026-09-23T15:02:11Z",
        "closed_at": "2026-09-23T15:02:11Z",
        "expires_at": "2026-09-23T15:02:11Z"
      }
    ],
    "companies": [
      {
        "company": {
          "id": "string",
          "name": "string",
          "domain": "acme.com",
          "website_url": "https://example.com",
          "linkedin_url": "https://example.com",
          "ken_search_id": "string"
        },
        "match_count": 1,
        "newest_posted_at": "2026-09-23T15:02:11Z",
        "sources": [
          "string"
        ],
        "titles": [
          "string"
        ]
      }
    ],
    "total": 1,
    "totalMode": "capped",
    "notes": [
      "string"
    ],
    "pagination": {
      "next_cursor": "eyJpZCI6ODE1fQ"
    },
    "facets": {
      "sources": [
        {
          "value": "string",
          "count": 1
        }
      ],
      "countries": [
        {
          "value": "string",
          "count": 1
        }
      ],
      "seniority": [
        {
          "value": "string",
          "count": 1
        }
      ],
      "remote": [
        {
          "value": "string",
          "count": 1
        }
      ],
      "status": [
        {
          "value": "string",
          "count": 1
        }
      ]
    }
  }
}
```

## Export job postings

`POST /v1/job-postings/search/export` - operationId `job-postings.export`

| Permission | Rate limit |
| --- | --- |
| Search view and the `export` permission | 30 requests a minute per API key |

Export every job posting that matches your filters, as JSON or as a CSV file.

The body takes the same filters as `POST /v1/job-postings/search`, plus `format` (`json`, the
default, or `csv`) and `limit` (default 100). The export can return at most the smallest of
`limit`, 5,000 rows, and the rows left in this month's allowance. When more postings match, Kenso exports
nothing and answers `422`, so narrow the filters or raise `limit`. On Kenso Lifetime, the job post
results the license has left today cap the export too, and the rows it returns count against them.

Kenso charges one allowance row per returned row, once the whole export is in hand, and sets the
`X-Ken-Row-Count` header. A JSON export answers `application/json`, the postings in `data.signals`. A
CSV export answers the file, not an envelope: `Content-Type: text/csv; charset=utf-8` and
`Content-Disposition: attachment; filename="job-postings-{yyyyMMdd-HHmmss}.csv"`, the time in UTC. Errors are
JSON either way. A failed export uses nothing. The rows also count against the workspace's monthly
`jobsExportRows` fair-use quota. Check what is left with `GET /v1/job-postings/export-allowance`.

Errors:

- `400 validation_failed`: the body is not a JSON object, `format` is not `json` or `csv`,
or `limit` is not a whole number of at least 1. A `limit` above 5,000 counts as 5,000.
- `402 plan_required`: the workspace's plan does not include job post search. `error.refusal` carries
the code `PLAN_FEATURE_NOT_AVAILABLE` and the feature `job_post_search`.
- `402 plan_limit_reached`: the workspace has no export rows left this month, or another export used the
last of them first. `error.refusal` carries the code `JOBS_EXPORT_ROWS_LIMIT_REACHED`. On Kenso
Lifetime, it carries `LIFETIME_JOB_POST_RESULT_LIMIT_REACHED` when the license has no job post results left
today. They reset at 00:00 UTC.
- `413 validation_failed`: the body is larger than 1 MB.
- `422 export_limit_exceeded`: more postings match than the export may return. `details[0].count` is
the number that matched and `details[0].limit` the most this export could return.
- `422 export_too_large`: the export would be larger than 512 MB. Narrow the filters.
- `422 filter_required`: the body sets no filter.
- `422 validation_error`: a filter list has more than 100 items.
- `429 quota_exceeded`: the workspace used its monthly `jobsExportRows` quota. Wait for the time in
`Retry-After`.
- `503 service_unavailable`: too many exports are running, or job postings are not available right now.
Try again after the time in `Retry-After`, when the answer has one.
- `504 upstream_timeout`: job postings took too long to answer. Try again.

Requires Search view and the `export` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/job-postings/POST/v1/job-postings/search/export)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `JobPostingExportResult`.

| Field | Type | Description |
| --- | --- | --- |
| `signals` | array of JobPosting | The exported postings, each with its description. |
| `total` | integer (int32) | How many postings the export holds. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/job-postings/search/export" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "signals": [
      {
        "id": "string",
        "title": "string",
        "description": "string",
        "description_html": "string",
        "company": {
          "id": "string",
          "name": "string",
          "domain": "acme.com",
          "website_url": "https://example.com",
          "linkedin_url": "https://example.com",
          "ken_search_id": "string"
        },
        "company_name": "string",
        "company_domain": "acme.com",
        "location": "string",
        "locations": [
          "string"
        ],
        "country": "string",
        "remote": true,
        "workplace_type": "string",
        "department": "string",
        "team": "string",
        "employment_type": "string",
        "seniority": "string",
        "language": "string",
        "salary_raw": "string",
        "salary_currency": "USD",
        "salary_min": 0.5,
        "salary_max": 0.5,
        "salary_min_usd": 0.5,
        "salary_max_usd": 0.5,
        "equity": "string",
        "requisition_id": "string",
        "tags": [
          "string"
        ],
        "is_agency": true,
        "source": "string",
        "source_url": "https://example.com",
        "application_url": "https://example.com",
        "status": "string",
        "posted_at": "2026-09-23T15:02:11Z",
        "first_seen_at": "2026-09-23T15:02:11Z",
        "last_seen_at": "2026-09-23T15:02:11Z",
        "closed_at": "2026-09-23T15:02:11Z",
        "expires_at": "2026-09-23T15:02:11Z"
      }
    ],
    "total": 1
  }
}
```

## Get the job posting export allowance

`GET /v1/job-postings/export-allowance` - operationId `job-postings.get-export-allowance`

| Permission | Rate limit |
| --- | --- |
| Search view | 12,000 requests a minute per API key |

Get how many job posting rows the workspace may still export this calendar month. Check it before a large export.

The allowance equals the workspace's lead limit, in rows per month, and resets on the first of each month, UTC.
The answer holds `limit`, `used` (rows exported this month, including exports still running),
`remaining`, `maxPerExport`, `isUnlimited`, and the month's `periodStart` and
`periodEnd`. The call is free.

Errors:

- `503 service_unavailable`: job postings are not available right now, or Kenso could not read the
allowance. Try again.

Requires Search view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/job-postings/GET/v1/job-postings/export-allowance)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `JobPostingsExportAllowance`.

| Field | Type | Description |
| --- | --- | --- |
| `limit` | integer (int32) | Rows the workspace may export this month, equal to its lead limit. |
| `used` | integer (int32) | Rows exported this month, including exports still running. |
| `remaining` | integer (int32) | Rows left this month. 2147483647 when `isUnlimited` is true. |
| `maxPerExport` | integer (int32) | The most rows one export can return. |
| `isUnlimited` | boolean | True when the workspace has no export limit, for example because its lead limit is unlimited. |
| `periodStart` | string (date-time) | The start of this calendar month, UTC. |
| `periodEnd` | string (date-time) | The start of next calendar month, UTC, when the allowance resets. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/job-postings/export-allowance" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "limit": 1,
    "used": 1,
    "remaining": 1,
    "maxPerExport": 1,
    "isUnlimited": true,
    "periodStart": "2026-09-23T15:02:11Z",
    "periodEnd": "2026-09-23T15:02:11Z"
  }
}
```

## Resolve job filter values

`POST /v1/job-postings/filters/resolve` - operationId `job-postings.resolve-filters`

| Permission | Rate limit |
| --- | --- |
| Search view | 4,800 requests a minute per API key |

Turn partial company, job title or location text into the exact values a job posting filter accepts, for
type-ahead filter pickers.

Unlike a search, the call needs no filter. It is free and does not use the export allowance.

Errors:

- `400 validation_failed`: a field is not valid.
- `402 plan_required`: the workspace's plan does not include job post search. `error.refusal` carries
the code `PLAN_FEATURE_NOT_AVAILABLE` and the feature `job_post_search`.
- `413 validation_failed`: the body is larger than 1 MB.
- `503 service_unavailable`: job postings are not available right now. Try again.
- `504 upstream_timeout`: job postings took too long to answer. Try again.

Requires Search view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/job-postings/POST/v1/job-postings/filters/resolve)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `JobPostingFilterValues`.

| Field | Type | Description |
| --- | --- | --- |
| `companies` | array of JobPostingCompanyMatch | Companies whose name, a word of their name or their domain starts with the `companies` text, most open postings first. Empty when that text is under 2 characters. |
| `titles` | array of JobPostingValueCount | Job titles with a word that starts with the `titles` text, most open postings first. Empty when that text is under 2 characters. |
| `locations` | array of JobPostingLocationValue | Locations with a word that starts with the `locations` text, most open postings first. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/job-postings/filters/resolve" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "companies": [
      {
        "id": "string",
        "name": "string",
        "domain": "example.com",
        "open_jobs": 1
      }
    ],
    "titles": [
      {
        "value": "string",
        "count": 1
      }
    ],
    "locations": [
      {
        "value": "string",
        "count": 1,
        "kind": "country"
      }
    ]
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### JobPosting

An open or closed role a company published on its career site or a public job board.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The posting's id, as a string. Pass it to `GET /v1/job-postings/{jobPostingId}`. |
| `title` | string | no | The job title. |
| `description` | string | no | The job description as plain text. Left out when the search sets `includeDescription: false`, and null when unknown. |
| `description_html` | string | no | The job description as HTML. Left out when the search sets `includeDescription: false`, and null when unknown. |
| `company` | JobPostingCompany | no | The hiring company. Left out when the search sets `includeCompany: false`. |
| `company_name` | string | no | The hiring company's name. |
| `company_domain` | string | no | The hiring company's web domain, for example `acme.com`. Null when unknown. |
| `location` | string | no | The location as the posting states it. Null when it states none. |
| `locations` | array of string | no | Every location the posting lists. |
| `country` | string | no | The country of the job. Null when unknown. |
| `remote` | boolean | no | True when the job is remote, false when it is not. Null when the posting does not say. |
| `workplace_type` | string | no | The workplace type the posting states. Null when it states none. |
| `department` | string | no | The department the job is in. Null when unknown. |
| `team` | string | no | The team the job is in. Null when unknown. |
| `employment_type` | string | no | The employment type the posting states. Null when unknown. |
| `seniority` | string | no | The seniority of the role. Null when unknown. |
| `language` | string | no | The language the posting is written in. Null when unknown. |
| `salary_raw` | string | no | The salary text as the posting states it. Null when it states none. |
| `salary_currency` | string | no | The currency of `salary_min` and `salary_max`, for example `USD`. Null when unknown. |
| `salary_min` | number (double) | no | The lowest salary the posting states, in `salary_currency`. Null when unknown. |
| `salary_max` | number (double) | no | The highest salary the posting states, in `salary_currency`. Null when unknown. |
| `salary_min_usd` | number (double) | no | The lowest salary converted to US dollars. Null when unknown. |
| `salary_max_usd` | number (double) | no | The highest salary converted to US dollars. Null when unknown. |
| `equity` | string | no | The equity text as the posting states it. Null when it states none. |
| `requisition_id` | string | no | The employer's own requisition id for the job. Null when unknown. |
| `tags` | array of string | no | The tags the posting carries on its source. |
| `is_agency` | boolean | no | True when the hiring company is a recruiting or staffing agency. |
| `source` | string | no | The career site or job board Kenso read the posting from. |
| `source_url` | string | no | The posting's URL on its source. Null when unknown. |
| `application_url` | string | no | The URL to apply for the job. Null when unknown. |
| `status` | string | no | `open` while the posting is live and not expired, else `closed`. |
| `posted_at` | string (date-time) | no | When the employer posted the job, UTC. Null when the source does not say. |
| `first_seen_at` | string (date-time) | no | When Kenso first saw the posting, UTC. |
| `last_seen_at` | string (date-time) | no | When Kenso last saw the posting on its source, UTC. |
| `closed_at` | string (date-time) | no | When the posting closed, UTC. Null while it is open. |
| `expires_at` | string (date-time) | no | When the posting expires, UTC. Null when it has no end date. |

### JobPostingRevision

A saved version of a job posting.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fetched_at` | string (date-time) | no | When Kenso read this version, UTC. |
| `title` | string | no | The job title in this version. |
| `location` | string | no | The location in this version. Null when it stated none. |
| `salary_raw` | string | no | The salary text in this version. Null when it stated none. |
| `description` | string | no | The job description in this version as plain text. Null when unknown. |
| `description_html` | string | no | The job description in this version as HTML. Null when unknown. |
| `raw` | map of object | no | The source document of this version. Its fields depend on the source. |

### JobPostingCompany

The company that published a job posting.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The company's id in the job postings index, as a string. The `companies.ids` filter takes it. |
| `name` | string | no | The company's name. |
| `domain` | string | no | The company's web domain, for example `acme.com`. Null when unknown. |
| `website_url` | string | no | The company's website URL. Null when unknown. |
| `linkedin_url` | string | no | The company's LinkedIn page URL. Null when unknown. |
| `ken_search_id` | string | no | The company's Kenso company id (`kenCompanyId` elsewhere in the API), as a string. Null when Kenso has not matched the company. |

### JobPostingCompanyGroup

A hiring company on a `groupBy: "company"` search page.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `company` | JobPostingCompany | no | The company. |
| `match_count` | integer (int64) | no | How many of the company's postings match the search. |
| `newest_posted_at` | string (date-time) | no | When the company's newest matching posting was posted, UTC. Null when no matching posting says. |
| `sources` | array of string | no | The sources of the company's matching postings. |
| `titles` | array of string | no | Up to 20 distinct titles of the company's matching postings. |

### JobPostingPagination

How to get the next page of job postings.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `next_cursor` | string | no | Send it as `cursor` with the same filters to get the next page. Null on the last page. |

### JobPostingFacets

The matching postings counted by facet, each list largest count first.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sources` | array of JobPostingValueCount | no | The matching postings per source. |
| `countries` | array of JobPostingValueCount | no | The matching postings per country code. A posting in several countries counts in each. |
| `seniority` | array of JobPostingValueCount | no | The matching postings per seniority, without postings of unknown seniority. |
| `remote` | array of JobPostingValueCount | no | The matching postings per remote value, `true` or `false`. |
| `status` | array of JobPostingValueCount | no | The matching postings per status, `open` or `closed`. |

### JobPostingValueCount

A value and how many job postings have it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | string | no | The value, as the matching filter takes it. |
| `count` | integer (int64) | no | How many postings have the value: matching postings in a facet, open postings in a filter suggestion. |

### JobPostingCompanyMatch

A company that matches the `companies` text.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The company's id in the job postings index, as a string. The `companies.ids` filter takes it. |
| `name` | string | no | The company's name. |
| `domain` | string | no | The company's web domain. Null when unknown. |
| `open_jobs` | integer (int64) | no | How many open postings the company has. |

### JobPostingLocationValue

A location that matches the `locations` text.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | string | no | The value, as the matching filter takes it. |
| `count` | integer (int64) | no | How many postings have the value: matching postings in a facet, open postings in a filter suggestion. |
| `kind` | string | no | What the location is: `country`, `region`, `state` or `city`. |

All resources: [/docs.md](/docs.md).
