Introduction - Signalbase Documentation

Welcome to the People API

The People API is ICP-style people discovery across Signalbase’s signal-driven dataset. Filter by title, function, seniority, geography, and company attributes to build a target list — and every person you get back arrives with a matched_signal inline (a funding round, acquisition, or job change) that tells you why now: the timing reason to reach out, not just who matches your ICP. This is not a static contact database. People whose company has no active signal within the requested window are excluded by design. It is also a search endpoint — it reads existing records and never triggers the enrichment pipeline. You can also use it as a precise lookup rather than an ICP browse: pass an identifier — a person’s linkedin_url, or a company_domain / company_linkedin_url — to resolve a specific record and return its people with their signals. See Identifier Lookup below.

Search People Endpoint

View the complete OpenAPI specification

Why now: `matched_signal` and `is_latest_signal`

Every result includes a matched_signal — the latest signal that matched your filters. Because Signalbase filters first and then surfaces the latest matching signal, matched_signal is always consistent with your query, but it is not necessarily the person’s newest overall signal. The is_latest_signal boolean tells you which case you’re in:

true — the matched signal is also the person’s most recent signal.
false — an older signal matched your filters, and the person has a more recent signal that did not match.

When you don’t pass signal_type, matched_signal is the person’s newest qualifying signal of any supported type (funding_round, acquisition, job_change), so types can mix across a page. Pass signal_type to pin the surface to specific type(s).

Identifier Lookup

Instead of browsing an ICP, you can resolve a specific person or company and return its people with their signals. Any of these identifiers matches the source record by canonical (exact) equality — all accepted URL variants (scheme, www., trailing slash) are normalized before matching:

Parameter	Matches	Notes
`linkedin_url`	A specific person	Personal profile URL (`/in/` or legacy `/pub/`). Matches current employees and job-change subjects. Pass a company page to `company_linkedin_url` instead.
`company_domain`	People at a company	Company website domain, e.g. `novartis.com`
`company_linkedin_url`	People at a company	Company LinkedIn URL, e.g. `linkedin.com/company/novartis`

All-time by default. When any identifier is set, signal_date_range defaults to all-time rather than 12m — a lookup means “everything on record for this person/company”, not “matched something in the last 12 months”. Pass signal_date_range explicitly to still narrow the window. Behavior. Invalid identifier syntax returns 400. A valid identifier that resolves to nothing returns an empty data set with a 200. Identifiers AND with any other filters you pass.

# Everything on record for one person
curl -X GET "https://www.trysignalbase.com/api/v2/people?linkedin_url=https://www.linkedin.com/in/jane-doe" \
  -H "Authorization: Bearer YOUR_API_KEY"

# All people at a company, by domain
curl -X GET "https://www.trysignalbase.com/api/v2/people?company_domain=novartis.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Count Mode

You can get the total number of people 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/people?count=true&seniority=c_level&signal_type=funding_round&signal_date_range=6m" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": [],
  "pagination": {
    "currentPage": 1,
    "totalPages": 12,
    "totalCount": 1183,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "meta": {
    "endpoint": "people.list",
    "creditsUsed": 0
  }
}

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

Key Features

Signal-backed results: Every person carries a matched_signal explaining the timing to reach out
Taxonomy-aware filters: Filter by title, function, and seniority with word-boundary matching (no COO → Coordinator false positives)
Company targeting: Narrow by company size band and industry
Geography: Filter by country (person or company), person-only country (person_countries), and city (job-change people)
Flexible lookback: Control the signal window with signal_date_range (e.g. 30d, 6m, 2y)
Pagination support: Up to 100 results per page
Credit-based usage: Transparent credit consumption per API call, with a free count mode

How Filtering Works

Different filters AND together; comma-separated values within one filter OR together. For example, seniority=c_level,vp&country=US returns people who are (C-level OR VP) AND in the US.
A person qualifies if any of their signals matches the filters; the latest matching one is surfaced as matched_signal.
Results merge two sources (current company employees and job-change subjects) and are deduplicated before pagination by normalized person LinkedIn URL, falling back to normalized name + company domain/LinkedIn/name.
Default sort: matched_signal.date descending (most recent why-now first).

Source-dependent Fields

Some fields are only populated from one of the two underlying sources:

Field	Behavior
`city` (person)	Only job-change-sourced people carry a city. Setting the `city` filter excludes employee-sourced people.
`country` (person)	Only job-change-sourced people carry their own country. Setting the `person_countries` filter excludes employee-sourced people and job-change people without a known person country.
`company.size_band`	Requires a linked company with a known headcount. Setting `company_size` excludes people whose company headcount is unknown.
`company.city`	Always `null` today — companies do not carry a city field yet.

Active vs. Former

The endpoint is currently active-only (current employees). include_former=true returns a 400 because job-change records have no current/former semantics yet, so honoring the flag would silently mix records. Until that data dependency is defined, every result has status: "active".

Privacy

Person names are masked in responses (first name + last initial, e.g. Sarah K.), consistent with the Job Change and Employees endpoints. Use linkedin_url to identify a specific person.

Authentication

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

curl -X GET "https://www.trysignalbase.com/api/v2/people?page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter names are validated strictly: an unrecognized query parameter returns a 400 listing the supported names. Spellings from the signal endpoints get a pointer to the equivalent here — e.g. countries → country, team_size → company_size, type → signal_type, person_country → person_countries. Previously unknown names were silently ignored, so a typo’d filter returned the full unfiltered dataset.

Pagination

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

Person Filters

Parameter	Type	Description
`title`	string	Title or comma-separated list (e.g. `CTO,VP of Engineering`). Word-boundary taxonomy match
`function`	string	Comma-separated function ids. See People Functions
`seniority`	string	Comma-separated seniority ids. See People Seniorities

Geography

Parameter	Type	Description
`country`	string	ISO 3166-1 alpha-2 code or comma-separated list (e.g. `US,NL`). Matches person or company country
`person_countries`	string	ISO 3166-1 alpha-2 code or comma-separated list (e.g. `GB,IE`). Matches the person’s own country only — no company fallback. Person location exists on a minority of records (job-change sourced), so this favors precision over recall — see Source-dependent fields
`exclude_countries`	string	Comma-separated country codes to exclude (denylist, e.g. `CN`). A person is excluded when either their company country or their own person country matches; rows with an unknown country on a side are kept
`city`	string	Free-text city (partial match). Job-change people only — see Source-dependent fields

Company Filters

Parameter	Type	Description
`company_size`	string	Comma-separated size bands. See Company Size Bands
`industry`	string	Industry or comma-separated list (case-insensitive exact match)

Identifier Lookup

Resolve a specific person or company instead of browsing an ICP — see Identifier Lookup. Setting any of these defaults signal_date_range to all-time.

Parameter	Type	Description
`linkedin_url`	string	Person LinkedIn profile URL (`/in/` or `/pub/`). Matches employees and job-change subjects
`company_domain`	string	Company website domain (e.g. `novartis.com`) — returns the people at that company
`company_linkedin_url`	string	Company LinkedIn URL (e.g. `linkedin.com/company/novartis`)

Signal Filters

Parameter	Type	Default	Description
`signal_type`	string	—	Comma-separated signal type(s): `funding_round`, `acquisition`, `job_change`. Pins `matched_signal` to these types
`signal_date_range`	string	`12m` *	Lookback window as `<n><unit>` with unit `d`/`w`/`m`/`y` — e.g. `30d`, `6m`, `12m`, `2y`. *Defaults to all-time when an identifier lookup is set

Active / Former

Parameter	Type	Default	Description
`include_former`	boolean	`false`	Currently only `false` is supported. `true` returns `400` — see Active vs. Former

Count Mode

Parameter	Type	Description
`count`	string	Set to `true` to return only the total count, without data rows and without consuming credits

Enum Values

Functions

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

Seniorities

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

Company Size Bands

1-10, 11-50, 51-100, 101-250, 251-500, 501-1000, 1000-plus

Signal Types

funding_round, acquisition, job_change

Response Structure

Each result includes the person, their company, is_latest_signal, and the inline matched_signal:

{
  "success": true,
  "data": [
    {
      "name": "Sarah K.",
      "linkedin_url": "https://www.linkedin.com/in/sarah-k",
      "title": "Chief Technology Officer",
      "status": "active",
      "city": null,
      "country": null,
      "company": {
        "name": "NextGen Software",
        "domain": "nextgensoftware.com",
        "linkedin_url": "https://www.linkedin.com/company/nextgensoftware",
        "country": "NL",
        "city": null,
        "size_band": "101-250",
        "industry": "Technology"
      },
      "is_latest_signal": true,
      "matched_signal": {
        "type": "funding_round",
        "date": "2026-05-12",
        "summary": "Series B, $40M led by Accel",
        "source_url": "https://techcrunch.com/2026/05/12/nextgen-series-b"
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 12,
    "totalCount": 1183,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "meta": {
    "endpoint": "people.list",
    "creditsUsed": 1,
    "creditsRemaining": 4999
  }
}

Error Handling

The API returns standard HTTP status codes:

200: Success
400: Bad request — invalid filter value (unknown function/seniority/company_size/signal_type, malformed signal_date_range, include_former=true, or invalid identifier syntax in linkedin_url/company_domain/company_linkedin_url). Note: a valid identifier that resolves to no records returns 200 with an empty data set, not 400
401: Unauthorized — invalid or missing API key
402: Insufficient credits
429: Rate limit exceeded
500: Internal server error

Error responses include:

{
  "success": false,
  "error": "Invalid seniority value: exec. Accepted values: founder, c_level, vp, director, head, lead, manager."
}

Example Usage

CTOs in the Netherlands at mid-size companies

curl -X GET "https://www.trysignalbase.com/api/v2/people?title=CTO&country=NL&company_size=51-100,101-250" \
  -H "Authorization: Bearer YOUR_API_KEY"

C-level people at recently funded companies

curl -X GET "https://www.trysignalbase.com/api/v2/people?seniority=c_level&signal_type=funding_round&signal_date_range=6m" \
  -H "Authorization: Bearer YOUR_API_KEY"

Engineering leaders in SaaS

curl -X GET "https://www.trysignalbase.com/api/v2/people?function=engineering&industry=SaaS&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Look up one person by LinkedIn URL

curl -X GET "https://www.trysignalbase.com/api/v2/people?linkedin_url=https://www.linkedin.com/in/jane-doe" \
  -H "Authorization: Bearer YOUR_API_KEY"

All people at a company, by domain

curl -X GET "https://www.trysignalbase.com/api/v2/people?company_domain=novartis.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

​Welcome to the People API

Search People Endpoint

​Why now: matched_signal and is_latest_signal

​Identifier Lookup

​Count Mode

​Key Features

​How Filtering Works

​Source-dependent Fields

​Active vs. Former

​Privacy

​Authentication

​Query Parameters

​Pagination

​Person Filters

​Geography

​Company Filters

​Identifier Lookup

​Signal Filters

​Active / Former

​Count Mode

​Enum Values

​Response Structure

​Error Handling

​Example Usage

​CTOs in the Netherlands at mid-size companies

​C-level people at recently funded companies

​Engineering leaders in SaaS

​Look up one person by LinkedIn URL

​All people at a company, by domain

Welcome to the People API

Why now: `matched_signal` and `is_latest_signal`

Identifier Lookup

Count Mode

Key Features

How Filtering Works

Source-dependent Fields

Active vs. Former

Privacy

Authentication

Query Parameters

Pagination

Person Filters

Geography

Company Filters

Identifier Lookup

Signal Filters

Active / Former

Count Mode

Enum Values

Response Structure

Error Handling

Example Usage

CTOs in the Netherlands at mid-size companies

C-level people at recently funded companies

Engineering leaders in SaaS

Look up one person by LinkedIn URL

All people at a company, by domain