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

# Retrieve Active and Historical Job Posts for a Company

> Fetch historical and active job postings for any company in Clodura's database. Analyze hiring trends, seniority signals, and tech stack indicators.

The Job Posts endpoint retrieves historical and active job postings from a specific organization, giving you a detailed window into a company's hiring activity. Job data is sourced from LinkedIn and other platforms, enriched with structured metadata including job function, seniority level, hiring areas (tech stack and domain expertise), and geographic location. Sales and revenue teams commonly use this data to identify buying intent signals — a company aggressively hiring in Engineering or DevOps roles signals investment and potential budget for new tools.

You must provide either an `organisationId` or `orgLinkedinUrl` to identify the target company, as well as a date range using `postedSince` and `postedUntil`. The endpoint returns up to 200 jobs per request.

<Note>
  **Credit cost:** 2 credits per API request regardless of how many jobs are returned.

  **Capacity:** Maximum of 200 job postings per company per request. Use pagination (`page`) to retrieve additional results.
</Note>

## Endpoint

`POST /api/v1/organisation/jobpost`

## Request

### Headers

| Header         | Value                |
| -------------- | -------------------- |
| `X-API-KEY`    | Your Clodura API key |
| `Content-Type` | `application/json`   |

### Body Parameters

<ParamField body="organisationId" type="string">
  Clodura's unique identifier for the company. Obtain this from the [Search Organizations](/api/company/search-organizations) endpoint. Required if `orgLinkedinUrl` is not provided.
</ParamField>

<ParamField body="orgLinkedinUrl" type="string">
  Full LinkedIn Company profile URL (e.g., `https://www.linkedin.com/company/circuitry-ai/`). Required if `organisationId` is not provided.
</ParamField>

<ParamField body="postedSince" type="date" required>
  Start date for filtering job postings. Format: `YYYY-MM-DD` (e.g., `2024-01-01`).
</ParamField>

<ParamField body="postedUntil" type="date" required>
  End date for filtering job postings. Format: `YYYY-MM-DD` (e.g., `2024-12-31`).
</ParamField>

<ParamField body="jobTitle" type="string">
  Exact match filter for a specific job title. Use this to find postings for a precise role.
</ParamField>

<ParamField body="jobFunction" type="array">
  Filter by department or business function. Accepted values include: `Admin`, `Analytics`, `Cloud`, `Customer Service`, `Cyber Security`, `Data Engineering`, `Devops`, `Engineering`, `Finance`, `HR`, `IT`, `Inside Sales`, `Legal`, `Marketing`, `Operations`, `Product Management`, `Sales`, `Security`, `Support`, `Testing`, `Training`, `Research`, and more.
</ParamField>

<ParamField body="city" type="array">
  Filter job postings by one or more cities. Refer to the [supported cities list](https://kb.clodura.ai/assets/files/city-0e179bb959324f64595aefc1197c7b63.txt).
</ParamField>

<ParamField body="state" type="array">
  Filter job postings by one or more states. Refer to the [supported states list](https://kb.clodura.ai/assets/files/state-18aa91fd534fa5f0e375cab69820ba76.txt).
</ParamField>

<ParamField body="country" type="array">
  Filter job postings by one or more countries. Refer to the [supported countries list](https://kb.clodura.ai/assets/files/country-bac0b920e008f616e8d3b86a9a593d6d.txt).
</ParamField>

<ParamField body="keywords" type="array">
  Keywords to match within job description text (e.g., `Kubernetes`, `GDPR`, `Agile`).
</ParamField>

<ParamField body="hiringAreas" type="array">
  Industry or technology focus areas derived from job descriptions. Accepted values include: `Artificial Intelligence`, `Machine Learning`, `Data Science`, `Cloud Computing`, `SaaS`, `DevOps`, `Cyber Security`, `Blockchain`, `IoT`, `Mobile Applications`, `Web Development`, `CRM Implementation`, `ERP Implementation`, `Salesforce Development`, and many more.
</ParamField>

<ParamField body="page" type="integer">
  Page number to retrieve. Maximum: `100`.
</ParamField>

<Warning>
  You must provide at least one of `organisationId` or `orgLinkedinUrl`. Requests that include neither will be rejected.
</Warning>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.clodura.ai/api/v1/organisation/jobpost \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "organisationId": "2389402640191586304",
      "postedSince": "2024-01-01",
      "postedUntil": "2024-12-31",
      "jobFunction": ["Engineering", "Sales"],
      "page": 1
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.clodura.ai/api/v1/organisation/jobpost"

  headers = {
      "X-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  payload = {
      "organisationId": "2389402640191586304",
      "postedSince": "2024-01-01",
      "postedUntil": "2024-12-31",
      "jobFunction": ["Engineering", "Sales"],
      "page": 1
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

## Response

A successful `200` response returns a paginated list of job postings for the specified organization.

<ResponseField name="organisationId" type="string">
  The Clodura ID of the queried organization.
</ResponseField>

<ResponseField name="orgLinkedinUrl" type="string">
  The LinkedIn URL of the queried organization.
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="pagination fields">
    <ResponseField name="page" type="integer">
      The current page number.
    </ResponseField>

    <ResponseField name="perPage" type="integer">
      Number of job records returned per page.
    </ResponseField>

    <ResponseField name="totalEntries" type="integer">
      Total number of job postings matching your filters.
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="jobs" type="array">
  <Expandable title="job object fields">
    <ResponseField name="jobId" type="string">
      Unique identifier for this job posting.
    </ResponseField>

    <ResponseField name="source" type="string">
      Platform where this job was posted (e.g., `LinkedIn`).
    </ResponseField>

    <ResponseField name="jobTitle" type="string">
      Title of the job posting.
    </ResponseField>

    <ResponseField name="jobType" type="string">
      Employment type (e.g., `Full time`, `Part time`, `Contract`).
    </ResponseField>

    <ResponseField name="jobSeniority" type="string">
      Seniority level required for the role (e.g., `Manager`, `Senior`, `Entry Level`).
    </ResponseField>

    <ResponseField name="jobFunction" type="string">
      Department or business function this role belongs to.
    </ResponseField>

    <ResponseField name="description" type="string">
      Full or summarized job description text.
    </ResponseField>

    <ResponseField name="location" type="string">
      Human-readable location of the job posting.
    </ResponseField>

    <ResponseField name="city" type="string">
      City where the job is located.
    </ResponseField>

    <ResponseField name="state" type="string">
      State where the job is located.
    </ResponseField>

    <ResponseField name="country" type="string">
      Country where the job is located.
    </ResponseField>

    <ResponseField name="datePosted" type="string">
      ISO 8601 timestamp of when the job was posted.
    </ResponseField>

    <ResponseField name="link" type="string">
      Direct URL to the original job posting.
    </ResponseField>

    <ResponseField name="hiringareas" type="array">
      Technology and domain focus areas identified in the job description (e.g., `UX`, `AI`, `IT`).
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "organisationId": "2389402640191586304",
  "orgLinkedinUrl": "https://www.linkedin.com/company/clodura-ai/",
  "pagination": {
    "page": 1,
    "perPage": 10,
    "totalEntries": 45,
    "totalPages": 5
  },
  "jobs": [
    {
      "jobId": "job_7721",
      "source": "LinkedIn",
      "jobTitle": "Software Engineering Manager",
      "jobType": "Full time",
      "jobSeniority": "Manager",
      "jobFunction": "Engineering",
      "description": "We are looking for an experienced Software Engineering Manager...",
      "location": "San Francisco, California, USA",
      "city": "San Francisco",
      "state": "California",
      "country": "USA",
      "datePosted": "2024-06-15T10:46:08Z",
      "link": "https://www.linkedin.com/jobs/view/123456789",
      "hiringareas": ["Machine Learning", "Cloud Computing", "AI"]
    }
  ]
}
```

## Error Codes

| Status | Meaning                                                                 |
| ------ | ----------------------------------------------------------------------- |
| `400`  | Bad request — malformed input or domain count exceeded                  |
| `401`  | Unauthorized — your API key is missing or invalid                       |
| `402`  | Payment required — credits exhausted; upgrade your plan or add credits  |
| `403`  | Forbidden — this endpoint requires a paid Clodura plan                  |
| `404`  | Not found — no job postings found for this organization                 |
| `409`  | Daily rate limit reached — maximum API calls for this endpoint exceeded |
| `422`  | Unprocessable entity — invalid parameter combination or malformed JSON  |
| `429`  | Rate limit exceeded — reduce request frequency or upgrade your plan     |