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

> ## Agent Instructions
> Forager is a REST API for B2B people, company and job post data: contact lookups (phone numbers, personal emails, work emails), person, company and job post search, and bulk data feeds.
> Server: https://api-v2.forager.ai. Send the API key in the X-API-KEY header. Most paths include {account_id}. Read FORAGER_API_KEY and FORAGER_ACCOUNT_ID from the environment; never put the key in client-side code, logs or prompts.
> To add Forager to a project, follow https://www.forager.ai/docs/guides/agent-quickstart.md. To pick an endpoint, read https://www.forager.ai/docs/guides/choose-an-endpoint.md. For end-to-end builds, see https://www.forager.ai/docs/recipes/overview.md.
> Most requests spend credits. Do not guess costs; use https://www.forager.ai/docs/api-overview/credit-pricing.md and ask the user before spending credits.
> Use only endpoints and fields defined in https://www.forager.ai/docs/openapi.yaml. Forager has no MCP server for the API yet; the /mcp endpoint on this site searches the documentation only.

# Job postings API

> Search job post events in the Forager job-post index.

## When to use this endpoint

You want job postings that match a title, a company, a location, a date range or a remote flag, for example to spot companies hiring for a role. `title` and `description` take a boolean text query.

## Example request

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/job_search/" \
  -H "X-API-KEY: $FORAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Senior Data Engineer",
  "is_remote": true,
  "is_active": true,
  "date_featured_start": "2026-10-01",
  "page": 1
}'
```

Set `FORAGER_API_KEY` and `FORAGER_ACCOUNT_ID` as in the [quickstart](https://www.forager.ai/docs/api-overview/send-your-first-request.md).

## Example response

```json 200 (illustrative values) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "search_results": [
    {
      "id": 9183021,
      "source": "linkedin",
      "date_featured": "2026-10-31",
      "organization": {
        "id": 90210,
        "name": "Acme Example",
        "domain": "acme.com",
        "linkedin_info": {
          "public_identifier": "acme-example",
          "industry": {
            "id": 4,
            "name": "Software Development"
          },
          "public_profile_url": "https://www.linkedin.com/company/acme-example/"
        }
      },
      "source_id": "4123456789",
      "url": "https://example.com/careers/senior-data-engineer",
      "title": "Senior Data Engineer",
      "description": null,
      "is_remote": true,
      "location": {
        "id": 10432,
        "name": "Austin, Texas, United States",
        "osm_locations": [
          {
            "id": 5,
            "name": "Texas",
            "place_type": "state"
          }
        ]
      },
      "is_active": true
    }
  ],
  "total_search_results": 1
}
```

## Credits

Each request costs **2 credits**. See [API credits and pricing](https://www.forager.ai/docs/api-overview/credit-pricing.md) for how credits are charged and how to check what you spent.


## OpenAPI

````yaml POST /api/{account_id}/datastorage/job_search/
openapi: 3.0.3
info:
  title: Forager public API
  version: 1.0.0
  description: Forager public API endpoints documentation
servers:
  - url: https://api-v2.forager.ai
security: []
tags:
  - name: Job Posts
    description: >-
      Search the Forager job-post index. Use these endpoints to find job
      postings by attributes such as title, location, posted date, or hiring
      organization, and to retrieve aggregate totals for a given query before
      paginating through full results.
  - name: Organizations
    description: >-
      Search the Forager organization index. Filter companies by attributes such
      as industry, headcount, location, keywords, and web technologies, and
      retrieve total match counts alongside the result set.
  - name: People
    description: >-
      Look up people and their records. Use the search endpoints to find people
      by role, employer, location, or skills, and the detail-lookup endpoints to
      fetch a full person record by ID, email, or phone number. Contact data has
      its own sections: Phones, Personal Emails, and Work Emails.
  - name: Phones
    description: >-
      Retrieve phone numbers for a known person. Provide identifying information
      (such as a LinkedIn handle or Forager ID) and get back the available phone
      numbers.
  - name: Personal Emails
    description: >-
      Retrieve personal email addresses for a known person. Returns addresses on
      free webmail / consumer providers (Gmail, Outlook, Yahoo, iCloud, Proton,
      and similar); corporate, educational, and other custom domains are
      excluded to keep deliverability high.
  - name: Work Emails
    description: >-
      Find and verify a person's work email address. Submit a lookup (single or
      bulk), poll the job for its result, and optionally receive the result by
      webhook when the job completes.
  - name: Websites
    description: >-
      Look up information about a website, including the organization that owns
      it and the technologies detected on the domain.
  - name: Users
    description: >-
      Manage your Forager account. Retrieve the current authenticated user,
      create and revoke API keys used to authenticate requests to the rest of
      the API, and review the credit balance-change log that records every
      lookup charge or adjustment against your account.
  - name: Autocomplete
    description: >-
      Resolve free-text input into the canonical IDs used elsewhere in the API.
      Each endpoint returns matching options for a search term (industries,
      organizations, organization keywords, locations, person skills, web
      technologies) so they can be passed as filters to the search endpoints.
  - name: Feedback
    description: >-
      Report verification feedback for contact data (phone numbers, personal
      emails, work emails) returned by Forager person lookups. Use these
      endpoints to submit whether a contact value is valid/invalid and whether
      it belongs to the matched person — every submission is stored as a new row
      and is used to improve the accuracy of future lookups.
paths:
  /api/{account_id}/datastorage/job_search/:
    post:
      tags:
        - Job Posts
      summary: Job post event search
      description: Job post event search.
      operationId: datastorage_job_search_create
      parameters:
        - in: path
          name: account_id
          schema:
            type: integer
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobPostEventSearch'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/JobPostEventSearch'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/JobPostEventSearch'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobPostEventSearchResponse'
          description: ''
        '403':
          $ref: '#/components/responses/AuthenticationFailed'
      security:
        - Api-Key: []
components:
  schemas:
    JobPostEventSearch:
      type: object
      description: JobPostEvent search request serializer.
      properties:
        page:
          type: integer
        job_source:
          $ref: '#/components/schemas/JobSourceEnum'
        date_featured_start:
          type: string
          format: date
        date_featured_end:
          type: string
          format: date
        organization_ids:
          type: array
          items:
            type: integer
          description: >-
            To get a list of IDs use <a
            href="/openapi/autocomplete/v1_organization_lookup">Organizations
            lookup endpoint</a>.
        title:
          type: string
          description: This field supports a boolean text search query.
        description:
          type: string
          description: This field supports a boolean text search query.
        is_remote:
          type: boolean
          nullable: true
        is_active:
          type: boolean
          default: true
        locations:
          type: array
          items:
            type: integer
          description: >-
            To get a list of IDs use <a
            href="/openapi/autocomplete/v1_location_lookup">Locations lookup
            endpoint</a>.
        locations_exclude:
          type: array
          items:
            type: integer
          description: >-
            To get a list of IDs use <a
            href="/openapi/autocomplete/v1_location_lookup">Locations lookup
            endpoint</a>.
    JobPostEventSearchResponse:
      type: object
      description: OrganizationJobPostEvent search response serializer.
      properties:
        search_results:
          type: array
          items:
            $ref: '#/components/schemas/JobPostEventSearchResult'
          readOnly: true
        total_search_results:
          type: integer
          minimum: 0
      required:
        - search_results
        - total_search_results
    JobSourceEnum:
      enum:
        - indeed
        - linkedin
        - angellist
      type: string
      description: |-
        * `indeed` - Indeed
        * `linkedin` - LinkedIn
        * `angellist` - AngelList
    JobPostEventSearchResult:
      type: object
      description: Serializer for the OrganizationJobPostEvent model for Jobs search API.
      properties:
        id:
          type: integer
          readOnly: true
        source:
          allOf:
            - $ref: '#/components/schemas/Source089Enum'
          readOnly: true
        date_featured:
          type: string
          format: date
        organization:
          allOf:
            - $ref: '#/components/schemas/ShortOrganization'
          readOnly: true
        source_id:
          type: string
          maxLength: 65
        url:
          type: string
          format: uri
          maxLength: 510
        title:
          type: string
          maxLength: 255
        description:
          type: string
          nullable: true
        is_remote:
          type: boolean
          title: Is remote?
        location:
          allOf:
            - $ref: '#/components/schemas/JobInnerLocation'
          readOnly: true
        is_active:
          type: boolean
          title: Is active?
      required:
        - date_featured
        - id
        - is_active
        - is_remote
        - location
        - organization
        - source
        - source_id
        - title
        - url
    Source089Enum:
      enum:
        - indeed
        - linkedin
        - angellist
      type: string
      description: |-
        * `indeed` - Indeed
        * `linkedin` - LinkedIn
        * `angellist` - AngelList
    ShortOrganization:
      type: object
      description: Short serializer for the Organization model.
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 255
        domain:
          type: string
          format: uri
          nullable: true
          maxLength: 200
        linkedin_info:
          allOf:
            - $ref: '#/components/schemas/OrganizationLinkedinInfo'
          readOnly: true
      required:
        - id
        - linkedin_info
        - name
    JobInnerLocation:
      type: object
      description: Serializer for the InnerLocation model for Jobs search API.
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 255
        osm_locations:
          type: array
          items:
            $ref: '#/components/schemas/JobOSMLocation'
          readOnly: true
      required:
        - id
        - name
        - osm_locations
    OrganizationLinkedinInfo:
      type: object
      description: Serializer for the OrganizationLinkedinInfo model.
      properties:
        public_identifier:
          type: string
          nullable: true
          maxLength: 255
        industry:
          allOf:
            - $ref: '#/components/schemas/LinkedinIndustry'
          readOnly: true
        public_profile_url:
          type: string
          nullable: true
          description: Get LinkedIn public profile URL.
          readOnly: true
      required:
        - industry
        - public_profile_url
    JobOSMLocation:
      type: object
      description: Serializer for the OSMLocation model for Jobs search API.
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 255
        place_type:
          type: string
          title: Type
          maxLength: 255
      required:
        - id
        - name
        - place_type
    LinkedinIndustry:
      type: object
      description: Serializer for the LinkedinIndustry document.
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 255
      required:
        - id
        - name
  responses:
    AuthenticationFailed:
      description: >-
        The X-API-KEY header is missing, the key is not valid, or the key does
        not have permission for this resource.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Authentication credentials were not provided.
  securitySchemes:
    Api-Key:
      type: apiKey
      in: header
      name: X-API-KEY

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.