Introduction - Signalbase Documentation

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.

Hiring Signals Endpoint

View the complete OpenAPI specification

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.

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:

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

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.

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 for naming conventions shared across signal APIs.

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.

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.

# 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

Text Search & Location

Parameter	Type	Description
`search`	string	Free-text search across company name, industry, job title, location, and city
`city`	string	Free-text search on city, location, and region
`countries`	string	Comma-separated country codes (e.g., `US,GB,DE`)
`states`	string	Comma-separated US state codes (e.g., `CA,NY,TX`)

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

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

Company Filters

Parameter	Type	Description
`company_domain`	string	Recommended. Company website domain (e.g. `novartis.com`). Strict match — see Matching by company URL
`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:

{
  "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:

{
  "success": false,
  "error": "Error message description"
}

Example Usage

Filter by Position and Date Preset

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

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

Filter by Department and Seniority with Sorting

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

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"

​Welcome to the Hiring Signals API

Hiring Signals Endpoint

​Count Mode

​Key Features

​Response: company vs. job location

​Service Level

​Authentication

​Matching by Company URL (Recommended)

​Query Parameters

​Pagination

​Date Filters

​Text Search & Location

​Category Filters

​Role Category Filters

​Company Filters

​Sorting

​Response Structure

​Error Handling

​Example Usage

​Filter by Position and Date Preset

​Filter by Country and City

​Filter by Department and Seniority with Sorting

​Filter by Team Size and Subcategory

Welcome to the Hiring Signals API

Count Mode

Key Features

Response: company vs. job location

Service Level

Authentication

Matching by Company URL (Recommended)

Query Parameters

Pagination

Date Filters

Text Search & Location

Category Filters

Role Category Filters

Company Filters

Sorting

Response Structure

Error Handling

Example Usage

Filter by Position and Date Preset

Filter by Country and City

Filter by Department and Seniority with Sorting

Filter by Team Size and Subcategory