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

# Company hiring (job postings)

> Retrieve the list of open job postings for a given company

Get the list of open job postings indexed for a company using one company identifier (domain, company name, or LinkedIn URL). Results are sourced from TheirStack.

## Credits and rate limits

* Credits: **1 credit per job returned**. You are only charged for the jobs actually returned, and never for more jobs than your available credits allow. A lookup that returns no jobs costs nothing.
* Rate limit: **5 requests per second** per user

## Required identification

Provide at least one of:

* `company_domain`
* `company_name`
* `company_linkedin_url`

If none are provided, the API returns:

```json theme={null}
{
  "error": 400,
  "message": "Provide at least one of: company_domain, company_name, company_linkedin_url"
}
```

## Optional parameters

* `posted_within_days`: Only return jobs posted within the last N days. Must be one of the selectable look-back windows: `7`, `30`, `60`, `90`, or `180`. Defaults to `30` when omitted; any other value returns `422`.
* `limit`: Maximum number of jobs to return, a positive integer capped at **100**. Because billing is per job, use this to bound how many credits a single lookup can spend. Only enough pages to satisfy the limit are fetched.
* `full_description`: When `true`, return each job's full description. Defaults to `false`, in which case descriptions are truncated to a 300-character snippet.
* `job_title_keywords`: Array of strings. Only return jobs whose title matches one of these keywords.
* `excluded_job_title_keywords`: Array of strings. Exclude jobs whose title matches one of these keywords.
* `job_description_keywords`: Array of strings. Only return jobs whose description contains one of these keywords.
* `excluded_job_description_keywords`: Array of strings. Exclude jobs whose description contains one of these keywords.
* `job_country_codes`: Array of 2-letter ISO 3166-1 alpha-2 country codes (e.g. `US`, `FR`). Only return jobs located in these countries. Codes are case-insensitive.
* `excluded_job_country_codes`: Array of 2-letter ISO 3166-1 alpha-2 country codes. Exclude jobs located in these countries.

Each keyword filter must be an array of strings, otherwise the API returns `422`. Invalid country codes also return `422`.

## Example request

```json theme={null}
{
  "company_domain": "notion.so",
  "posted_within_days": 30,
  "limit": 10,
  "full_description": false,
  "job_title_keywords": ["engineer", "developer"],
  "excluded_job_title_keywords": ["intern"],
  "job_country_codes": ["US", "FR"]
}
```

## Example response

The `truncated` flag is `true` when more jobs matched than were returned (because of the `limit`, the 100-job ceiling, or your available credits).

```json theme={null}
{
  "total_jobs": 42,
  "truncated": true,
  "company": {
    "name": "Acme",
    "domain": "acme.com",
    "linkedin_url": "https://linkedin.com/company/acme"
  },
  "jobs": [
    {
      "job_title": "Senior Backend Engineer",
      "job_url": "https://example.com/jobs/1",
      "job_location": "Paris France",
      "employment_statuses": ["full_time"],
      "date_posted": "2026-05-30",
      "description": "Build cool stuff with Rails.",
      "hiring_team": [
        {
          "name": "Alice Doe",
          "title": "Engineering Manager",
          "linkedin_url": "https://linkedin.com/in/alice"
        }
      ]
    }
  ]
}
```


## OpenAPI

````yaml POST /accounts/company_hiring
openapi: 3.0.1
info:
  title: Pipecorn Accounts API
  description: Pipecorn Accounts API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.pipecorn.com/api/v2/
security:
  - defaultApiKey: []
paths:
  /accounts/company_hiring:
    post:
      summary: Get company job postings
      description: >-
        Retrieve the list of open job postings indexed for a company.


        **Credits:** 1 credit per job returned. You are only charged for the
        jobs actually returned, and never for more jobs than your available
        credits allow. A lookup that returns no jobs costs nothing.


        **Rate limit:** 5 requests per second
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                company_domain:
                  type: string
                  description: Company website domain
                  example: notion.so
                company_name:
                  type: string
                  description: Company name
                  example: Notion
                company_linkedin_url:
                  type: string
                  format: uri
                  description: LinkedIn company URL
                  example: https://www.linkedin.com/company/notionhq/
                posted_within_days:
                  type: integer
                  enum:
                    - 7
                    - 30
                    - 60
                    - 90
                    - 180
                  default: 30
                  description: >-
                    Only return jobs posted within the last N days. Must be one
                    of the selectable look-back windows: 7, 30, 60, 90, or 180.
                    Defaults to 30 when omitted; any other value returns 422.
                  example: 30
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: >-
                    Maximum number of jobs to return. A positive integer capped
                    at 100. Because billing is 1 credit per job, use this to
                    bound how many credits a single lookup can spend. Only
                    enough pages to satisfy the limit are fetched.
                  example: 10
                full_description:
                  type: boolean
                  default: false
                  description: >-
                    When true, return each job's full description. Defaults to
                    false, in which case descriptions are truncated to a
                    300-character snippet.
                  example: false
                job_title_keywords:
                  type: array
                  items:
                    type: string
                  description: Only return jobs whose title matches one of these keywords.
                  example:
                    - engineer
                    - developer
                excluded_job_title_keywords:
                  type: array
                  items:
                    type: string
                  description: Exclude jobs whose title matches one of these keywords.
                  example:
                    - intern
                job_description_keywords:
                  type: array
                  items:
                    type: string
                  description: >-
                    Only return jobs whose description contains one of these
                    keywords.
                  example:
                    - rails
                    - ruby
                excluded_job_description_keywords:
                  type: array
                  items:
                    type: string
                  description: >-
                    Exclude jobs whose description contains one of these
                    keywords.
                  example:
                    - php
                job_country_codes:
                  type: array
                  items:
                    type: string
                  description: >-
                    Only return jobs located in these countries. 2-letter ISO
                    3166-1 alpha-2 country codes (e.g. US, FR);
                    case-insensitive.
                  example:
                    - US
                    - FR
                excluded_job_country_codes:
                  type: array
                  items:
                    type: string
                  description: >-
                    Exclude jobs located in these countries. 2-letter ISO 3166-1
                    alpha-2 country codes (e.g. US, FR); case-insensitive.
                  example:
                    - CA
            examples:
              by_domain:
                summary: Lookup by domain
                value:
                  company_domain: notion.so
              by_linkedin_url:
                summary: Lookup by LinkedIn URL
                value:
                  company_linkedin_url: https://www.linkedin.com/company/notionhq/
              by_name:
                summary: Lookup by name
                value:
                  company_name: Notion
              with_posted_within_days:
                summary: Filter by recency
                value:
                  company_domain: notion.so
                  posted_within_days: 30
              with_filters_and_limit:
                summary: Filter by title and country with a limit
                value:
                  company_domain: notion.so
                  limit: 10
                  full_description: false
                  job_title_keywords:
                    - engineer
                    - developer
                  excluded_job_title_keywords:
                    - intern
                  job_country_codes:
                    - US
                    - FR
      responses:
        '200':
          description: Successfully retrieved job postings
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_jobs:
                    type: integer
                    description: >-
                      Total number of matching job postings (may exceed the
                      number returned)
                    example: 42
                  truncated:
                    type: boolean
                    description: >-
                      True when more jobs matched than were returned (because of
                      the limit, the 100-job ceiling, or your available
                      credits).
                    example: true
                  company:
                    type: object
                    description: The hiring company, resolved from the first matching job.
                    properties:
                      name:
                        type: string
                        example: Acme
                      domain:
                        type: string
                        example: acme.com
                      linkedin_url:
                        type: string
                        format: uri
                        example: https://linkedin.com/company/acme
                  jobs:
                    type: array
                    description: List of job postings
                    items:
                      type: object
                      properties:
                        job_title:
                          type: string
                          description: Title of the job posting
                          example: Senior Backend Engineer
                        job_url:
                          type: string
                          format: uri
                          description: URL of the job posting
                          example: https://example.com/jobs/1
                        job_location:
                          type: string
                          description: Location of the job posting
                          example: Paris France
                        employment_statuses:
                          type: array
                          items:
                            type: string
                          description: >-
                            Employment statuses for the job (e.g. full_time,
                            part_time)
                          example:
                            - full_time
                        date_posted:
                          type: string
                          format: date
                          description: Date the job was posted
                          example: '2026-05-30'
                        description:
                          type: string
                          description: >-
                            Job description. Truncated to a 300-character
                            snippet unless full_description is true.
                          example: Build cool stuff with Rails.
                        hiring_team:
                          type: array
                          description: List of people involved in hiring for this job
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                example: Alice Doe
                              title:
                                type: string
                                example: Engineering Manager
                              linkedin_url:
                                type: string
                                format: uri
                                example: https://linkedin.com/in/alice
              example:
                total_jobs: 42
                truncated: true
                company:
                  name: Acme
                  domain: acme.com
                  linkedin_url: https://linkedin.com/company/acme
                jobs:
                  - job_title: Senior Backend Engineer
                    job_url: https://example.com/jobs/1
                    job_location: Paris France
                    employment_statuses:
                      - full_time
                    date_posted: '2026-05-30'
                    description: Build cool stuff with Rails.
                    hiring_team:
                      - name: Alice Doe
                        title: Engineering Manager
                        linkedin_url: https://linkedin.com/in/alice
        '400':
          description: Missing required company identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 400
                message: >-
                  Provide at least one of: company_domain, company_name,
                  company_linkedin_url
        '401':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 401
                message: Insufficient credits
        '422':
          description: >-
            Unprocessable entity. Returned for an invalid filter (each keyword
            filter must be an array of strings), an invalid country code (use
            2-letter ISO 3166-1 alpha-2 codes), a non-positive or non-integer
            limit, or when credits run out mid-request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 422
                message: >-
                  Invalid country code(s): USA. Use 2-letter ISO 3166-1 alpha-2
                  codes (e.g. US, FR).
        '429':
          description: Rate limit exceeded (5 requests per second)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 429
                message: Too many requests
components:
  schemas:
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    defaultApiKey:
      type: apiKey
      in: header
      description: Your API key
      name: X-API-KEY

````