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

# Introduction

> Access real-time hiring signals with position, department, seniority, and location filters

## Welcome to the Hiring Signals API

The Hiring Signals API provides timely insights on open job postings across the web. Track which companies are hiring, what roles they're filling, and where — with precise filters for positions, departments, seniority levels, team size, applicant counts, and geographic targeting.

<Card title="Hiring Signals Endpoint" icon="user-plus" href="/api-reference/hiring-signals/endpoint/get">
  View the complete OpenAPI specification
</Card>

## Count Mode

You can get the total number of results matching any filter combination **without consuming credits** by adding `count=true` to your request. This returns an empty `data` array with full pagination metadata, including `totalCount`.

```bash theme={null}
curl -X GET "https://www.trysignalbase.com/api/v2/signals/hiring?count=true&positions=CTO&date_preset=last_30d" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": [],
  "pagination": {
    "currentPage": 1,
    "totalPages": 8,
    "totalCount": 156,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "meta": {
    "endpoint": "signals.hiring",
    "creditsUsed": 0
  }
}
```

<Tip>Use count mode to preview how many results match your filters before fetching actual data. This is useful for building filter UIs, showing result counts, or validating queries — all at zero credit cost.</Tip>

## Key Features

* **Real-time Signals**: Hiring signals aggregated continuously from web sources
* **Role-aware Filters**: Filter by positions, departments, and seniority levels
* **Location Targeting**: Filter by country, US state, and city
* **Category Filters**: Filter by industry categories and keyword-based subcategories
* **Company Filters**: Filter by team size and applicant count ranges
* **Flexible Sorting**: Sort by date posted, title, company name, location, or ingestion date
* **Pagination Support**: Efficiently retrieve large datasets with up to 100 results per page
* **Credit-based Usage**: Transparent credit consumption per API call

## Response: company vs. job location

Each row includes **`companyCountry`** (employer HQ) and **`jobCountry`** (listing location). Signal rows also include **`companySubcategory`** when the company has been classified. See [Company fields in signal responses](/enums#company-fields-in-signal-responses) for naming conventions shared across signal APIs.

The same distinction applies to filtering: the `countries` parameter matches either country (job listing **or** company HQ), while `job_countries` matches the job listing country only. Use `job_countries` when you care about where the job is, not where the company is based — e.g. a Berlin listing from a US-headquartered company matches `job_countries=DE` but not `job_countries=US`.

## Service Level

* **Rate Limit**: Based on your subscription tier
* **Uptime**: 99% guaranteed uptime
* **Data Freshness**: Real-time aggregation ensures up-to-date signals
* **Maximum Results**: Up to 100 results per page

## Authentication

All API endpoints require a Bearer token in the `Authorization` header.

```bash theme={null}
curl -X GET "https://www.trysignalbase.com/api/v2/signals/hiring?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Matching by Company URL (Recommended)

If you know a company's website domain or LinkedIn page, query by URL instead of by name. Name search is fuzzy and can return lookalikes (`Novartis` also matches `Novartis UK`); URL identifiers match exactly one company.

```bash theme={null}
# By website domain
curl -X GET "https://www.trysignalbase.com/api/v2/signals/hiring?company_domain=novartis.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

# By LinkedIn company page
curl -X GET "https://www.trysignalbase.com/api/v2/signals/hiring?company_linkedin_url=linkedin.com/company/novartis" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Accepted input formats.** URL identifiers are normalized before matching, so equivalent variants return the same results:

* `company_domain`: `novartis.com`, `www.novartis.com`, `https://www.novartis.com/`, `https://novartis.com/any/path` — scheme, `www.`, port, path and trailing slash are ignored. Values that can't be reduced to a domain return `400`.
* `company_linkedin_url`: `linkedin.com/company/novartis`, `https://www.linkedin.com/company/Novartis/` — `http`/`https`, `www.` and trailing slash are ignored, the slug is case-insensitive. URLs that aren't LinkedIn *company* pages (e.g. personal `/in/` profiles) return `400`.

**Strict matching.** When a URL identifier is provided, the API never falls back to fuzzy name matching: if no company matches, the result is empty. Identifiers combine with `AND` — `company_domain=novartis.com&company_name=Acme` returns empty because they disagree.

**Match confidence.** Every result row includes `match_confidence`:

| Value   | Meaning                                                |
| ------- | ------------------------------------------------------ |
| `exact` | Matched via `company_domain` or `company_linkedin_url` |
| `fuzzy` | Matched via `company_name` partial match only          |
| `none`  | No company identifier was part of the query            |

## Query Parameters

### Pagination

| Parameter | Type    | Default | Description                 |
| --------- | ------- | ------- | --------------------------- |
| `page`    | integer | 1       | Page number                 |
| `limit`   | integer | 20      | Results per page (max: 100) |

### Date Filters

| Parameter     | Type   | Description                                                                                                  |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `dateFrom`    | string | Filter by date from (ISO-8601 string)                                                                        |
| `dateTo`      | string | Filter by date to (ISO-8601 string)                                                                          |
| `date_preset` | string | Relative date shorthand — takes precedence over `dateFrom`/`dateTo`. See [Date Presets](/enums#date-presets) |

### Text Search & Location

| Parameter           | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `search`            | string | Free-text search across company name, industry, job title, location, and city                                                                                                                                                                                                                                                                                                                                                                                |
| `description`       | string | Full-text keyword search over the **job description body only**. Opt-in and separate from `search` — use it to find postings mentioning specific keywords, skills, or tools (e.g. `description=Kubernetes`). Matches whole words (not substrings) and supports `websearch`-style syntax: space-separated terms are ANDed, `"quoted phrases"` match in order, `OR` and leading `-` (exclude) are honored (e.g. `description=kubernetes OR terraform -intern`) |
| `city`              | string | Free-text search on city, location, and region                                                                                                                                                                                                                                                                                                                                                                                                               |
| `countries`         | string | Comma-separated country codes (e.g., `US,GB,DE`). Allowlist; matches the job listing country **or** the company HQ country                                                                                                                                                                                                                                                                                                                                   |
| `exclude_countries` | string | Comma-separated country names or codes to **exclude** (denylist, e.g. `China`). A signal is excluded when **either** the job listing country or the company HQ matches; rows with an unknown country on a side are kept                                                                                                                                                                                                                                      |
| `job_countries`     | string | Comma-separated country codes matching the job listing location **only**, ignoring company HQ (e.g., `US,GB`)                                                                                                                                                                                                                                                                                                                                                |
| `states`            | string | Comma-separated US state codes (e.g., `CA,NY,TX`)                                                                                                                                                                                                                                                                                                                                                                                                            |

<Warning>`countries` and `job_countries` are ANDed if both are supplied — `countries=US&job_countries=GB` is almost always empty. Use one or the other, not both.</Warning>

### Category Filters

| Parameter       | Type   | Description                                                       |
| --------------- | ------ | ----------------------------------------------------------------- |
| `categories`    | string | Pipe-separated industry categories (e.g., `Technology\|Software`) |
| `subcategories` | string | Comma-separated subcategory IDs (e.g., `ai,fintech,saas`)         |

### Role Category Filters

| Parameter     | Type   | Description                                                                                           |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `positions`   | string | Comma-separated position IDs (e.g., `CEO,CTO,CFO`). See [Positions](/enums#positions)                 |
| `departments` | string | Comma-separated department IDs (e.g., `marketing,engineering`). See [Departments](/enums#departments) |
| `seniorities` | string | Comma-separated seniority IDs (e.g., `c_level,vp,director`). See [Seniorities](/enums#seniorities)    |

### Company Filters

| Parameter              | Type   | Description                                                                                                                                       |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `company_domain`       | string | **Recommended.** Company website domain (e.g. `novartis.com`). Strict match — see [Matching by company URL](#matching-by-company-url-recommended) |
| `company_linkedin_url` | string | **Recommended.** LinkedIn company URL (e.g. `linkedin.com/company/novartis`). Strict match                                                        |
| `company_name`         | string | Search by company name (partial match, fuzzy). Prefer the URL identifiers above                                                                   |
| `team_size`            | string | Comma-separated team size ranges (e.g., `1-10,11-50,51-200,201-1000,1000-plus`)                                                                   |
| `applicants`           | string | Comma-separated applicant ranges (e.g., `0-25,26-50,51-100,101-200,201-plus`)                                                                     |

### Sorting

| Parameter    | Type   | Default      | Description                                                                  |
| ------------ | ------ | ------------ | ---------------------------------------------------------------------------- |
| `sort_by`    | string | `created_at` | Sort field: `date_posted`, `created_at`, `title`, `company_name`, `location` |
| `sort_order` | string | `desc`       | Sort direction: `asc` or `desc`                                              |

## Response Structure

All successful responses follow this structure:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "uuid-here",
      "title": "Senior Software Engineer",
      "jobUrl": "https://www.linkedin.com/jobs/view/123456789",
      "location": "San Francisco, CA",
      "city": "San Francisco",
      "jobCountry": "US",
      "datePosted": "2024-11-01T00:00:00Z",
      "employmentType": "Full-time",
      "seniorityLevel": "Mid-Senior level",
      "jobFunction": "Engineering",
      "numApplicants": "45",
      "companyName": "NextGen Software",
      "companyIndustry": "Technology",
      "companyCountry": "US",
      "companySubcategory": "saas",
      "companyEmployeeCount": 250
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 50,
    "totalCount": 1000,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "meta": {
    "endpoint": "signals.hiring",
    "creditsUsed": 1
  }
}
```

## Error Handling

The API returns standard HTTP status codes:

* **200**: Success
* **401**: Unauthorized - Invalid or missing API key
* **429**: Rate limit exceeded
* **500**: Internal server error

Error responses include:

```json theme={null}
{
  "success": false,
  "error": "Error message description"
}
```

## Example Usage

### Filter by Position and Date Preset

```bash theme={null}
curl -X GET "https://www.trysignalbase.com/api/v2/signals/hiring?date_preset=last_30d&positions=CTO" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Filter by Country and City

```bash theme={null}
curl -X GET "https://www.trysignalbase.com/api/v2/signals/hiring?countries=US&city=San%20Francisco" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Filter by Job Location Only

Jobs located in Germany or the UK, regardless of where the hiring company is headquartered:

```bash theme={null}
curl -X GET "https://www.trysignalbase.com/api/v2/signals/hiring?job_countries=DE,GB&date_preset=last_30d" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Filter by Department and Seniority with Sorting

```bash theme={null}
curl -X GET "https://www.trysignalbase.com/api/v2/signals/hiring?departments=engineering&seniorities=c_level&sort_by=date_posted&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Filter by Team Size and Subcategory

```bash theme={null}
curl -X GET "https://www.trysignalbase.com/api/v2/signals/hiring?team_size=51-200&subcategories=ai,saas&date_preset=last_90d" \
  -H "Authorization: Bearer YOUR_API_KEY"
```