Introduction - Signalbase Documentation

Welcome to the Job Change Signals API

The Job Change Signals API provides timely insights on job changes across the web. Track role transitions and new hires with precise filters for positions, departments, and seniority levels, plus company and person-level LinkedIn targeting.

Job Change 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/job-changes?count=true&positions=CEO,CTO&date_preset=last_30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": [],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalCount": 93,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "meta": {
    "endpoint": "signals.job-changes",
    "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: Job change signals aggregated continuously from web sources
Role-aware Filters: Filter by positions, departments, and seniority levels
LinkedIn Targeting: Exact-match filters on person and company LinkedIn URLs
Field-specific Search: Search by person name, company name, new role, or keyword
Flexible Sorting: Sort by date, person name, or company name
Pagination Support: Efficiently retrieve large datasets with up to 100 results per page
Credit-based Usage: Transparent credit consumption per API call

Company vs. person location

Company headquarters use companyCountry and companySubcategory (when set). Person location uses personCountry, personCity, and related fields — see Company fields in signal responses.

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/job-changes?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/job-changes?company_domain=novartis.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

# By LinkedIn company page
curl -X GET "https://www.trysignalbase.com/api/v2/signals/job-changes?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

Parameter	Type	Description
`search`	string	Free-text search across company name, industry, person name, and role

Exact Match Filters

Parameter	Type	Description
`personLinkedinUrl`	string	Exact LinkedIn URL for a person
`company_linkedin_url`	string	Recommended. LinkedIn company URL (e.g. `linkedin.com/company/novartis`). Strict match — see Matching by company URL. Legacy alias: `companyLinkedinUrl`
`company_domain`	string	Recommended. Company website domain (e.g. `novartis.com`), matched via the linked company record. Strict match
`source`	string	Exact match on source: `linkedin`, `press_release`, `other`

Field-specific Search (partial match)

Parameter	Type	Description
`company_name`	string	Search by company name (partial match, fuzzy). Prefer `company_domain` or `company_linkedin_url` for strict matching
`new_role`	string	Search by new role / job title
`keyword`	string	Search by keyword tag

There is no person_name filter. For privacy (GDPR), people are queryable only by personLinkedinUrl, and personName is returned masked (first name + last initial). To locate a specific person, filter by their LinkedIn URL.

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

Sorting

Parameter	Type	Default	Description
`sort_by`	string	`occurred_at`	Sort field: `occurred_at`, `discovered_at`, `person_name`, `company_name`
`sort_order`	string	`desc`	Sort direction: `asc` or `desc`

Enum Values

Positions

"ceo", "cto", "cfo", "coo", "vp of engineering", "vp of sales", "vp of marketing",
"head of product", "head of growth", "head of engineering", "engineering manager",
"product manager", "sales manager", "marketing manager", "founder", "co-founder"

Departments

"marketing", "sales", "engineering", "product", "design", "operations", "finance", "people",
"data", "customer_success", "growth", "legal"

Seniorities

"founder", "c_level", "vp", "director", "head", "lead", "manager"

Response Structure

All successful responses follow this structure:

{
  "success": true,
  "data": [...],
  "pagination": {
    "currentPage": 1,
    "totalPages": 10,
    "totalCount": 200,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "meta": {
    "endpoint": "signals.job-changes",
    "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/job-changes?date_preset=last_30d&positions=CEO,CTO" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Company and Seniority

curl -X GET "https://www.trysignalbase.com/api/v2/signals/job-changes?company_name=Google&seniorities=c_level" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search by New Role with Sorting

curl -X GET "https://www.trysignalbase.com/api/v2/signals/job-changes?new_role=VP%20Engineering&sort_by=occurred_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Target by LinkedIn URLs

curl -X GET "https://www.trysignalbase.com/api/v2/signals/job-changes?personLinkedinUrl=https://www.linkedin.com/in/example&company_linkedin_url=linkedin.com/company/example" \
  -H "Authorization: Bearer YOUR_API_KEY"

​Welcome to the Job Change Signals API

Job Change Signals Endpoint

​Count Mode

​Key Features

​Company vs. person location

​Service Level

​Authentication

​Matching by Company URL (Recommended)

​Query Parameters

​Pagination

​Date Filters

​Text Search

​Exact Match Filters

​Field-specific Search (partial match)

​Role Category Filters

​Sorting

​Enum Values

​Response Structure

​Error Handling

​Example Usage

​Filter by Position and Date Preset

​Filter by Company and Seniority

​Search by New Role with Sorting

​Target by LinkedIn URLs

Welcome to the Job Change Signals API

Count Mode

Key Features

Company vs. person location

Service Level

Authentication

Matching by Company URL (Recommended)

Query Parameters

Pagination

Date Filters

Text Search

Exact Match Filters

Field-specific Search (partial match)

Role Category Filters

Sorting

Enum Values

Response Structure

Error Handling

Example Usage

Filter by Position and Date Preset

Filter by Company and Seniority

Search by New Role with Sorting

Target by LinkedIn URLs