# AI search
Source: https://api.tryspecter.com/api-ref/ai-search
Use a single endpoint and describe what you're looking for in plain English: "high-growth fintech companies in Germany founded after 2022" or "VC investors focused on climate." Specter handles the rest, mapping your query to the right filters and returning the matching records.
## What's covered
* All eight products are searchable through the single [AI search](/api-reference/search/ai-search) endpoint: companies, people, investors, talent signals, investor-interest signals, funding rounds, acquisitions, and IPOs.
* Every filter a product supports can be expressed in the query: geography, sector, growth stage, funding, headcount, revenue, seniority, dates, "similar to" a company, "backed by" an investor, and so on.
* Set `product` to force the product, or omit it to let Specter infer it; the response reports the product actually searched.
## Return types
Each result is the same rich object the product's own endpoints return, so you can chain and parse it identically.
| `product` | Returns |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| `company` | [Company](/api-reference/companies/get-company-by-id) |
| `people` | [Person](/api-reference/people/get-person-by-id) |
| `investors` | [Investor](/api-reference/investors/get-investor-by-id) |
| `talent_signals` | [Talent signal](/api-reference/talent-signals/get-talent-signals-by-date) |
| `interest_signals` | [Investor-interest signal](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date) |
| `funding_rounds` | [Funding round](/api-reference/transactions/get-funding-round-by-id) |
| `acquisitions` | [Acquisition](/api-reference/transactions/get-acquisition-by-id) |
| `ipos` | [IPO](/api-reference/transactions/get-ipo-by-id) |
## How to use
* Send `query` (required) and optionally `product`. Results page at 50; walk further with `page`.
* `total_count` (and the `X-Total-Count` header) reports how many records matched in total, so you can tell when there is more than the page you were given. To work through a larger set, keep paging, or save the search in the app and read it with the saved-search results endpoints.
## Notes
* Charged per block of results returned rather than per result, so a partial page is cheaper than a full one and a query that matches nothing is free. See the [AI search](/api-reference/search/ai-search) endpoint's "Costs" note for the block size and the exact figure.
* User-scoped filters are not supported: your network, CRM, or saved lists can't be resolved (the API authenticates as an organisation, not a user); such a query returns `422`.
# Authentication
Source: https://api.tryspecter.com/api-ref/auth
One team-level API key, sent on the X-API-Key header with every request.
Specter uses a single, team-level API key, so every call is tied to your firm's workspace. Rate and credit limits apply at the workspace level.
## Your API key
Your key lives in the [API Console](https://app.tryspecter.com/settings/api-console); copy it straight to your clipboard. No key yet? Click **Request API Access** there; requests are reviewed and approved within one business day.
Most investment teams work collaboratively from one source of truth. A shared key keeps data permissioning straightforward while still enforcing rate and credit limits at the workspace level.
## Making an authenticated request
```bash cURL theme={null}
curl --request GET \
--url https://app.tryspecter.com/api/v1/lists/companies \
--header 'X-API-Key: YOUR_API_KEY'
```
```python Python theme={null}
import requests
resp = requests.get(
"https://app.tryspecter.com/api/v1/lists/companies",
headers={"X-API-Key": "YOUR_API_KEY"},
)
print(resp.json())
```
```javascript JavaScript theme={null}
const res = await fetch("https://app.tryspecter.com/api/v1/lists/companies", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```
For a full walkthrough of your first request, see the [Quickstart](/api-ref/quickstart).
## Keep your key safe
Treat the key like a password; it grants access to your firm's data.
* Store it in an environment variable (e.g. `SPECTER_API_KEY`), never hard-coded in source.
* Never put it in client-side code, a browser, or a public repository.
* If a key is exposed, contact [api-support@tryspecter.com](mailto:api-support@tryspecter.com) to rotate it.
## Authentication errors
| Code | Meaning | Fix |
| ----- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `401` | Missing or invalid key | Confirm you're sending the `X-API-Key` header (not `Authorization: Bearer`) and the key is correct and active. |
| `403` | Key is valid, but your plan doesn't include this endpoint | Contact support to discuss access. |
For the full list, including credit (`402`) and rate (`429`) limits, see [Errors](/api-ref/errors).
## What the API can see
Lists and saved searches are only visible to the API once shared with it (a one-click toggle in the app) when created on the app; full rules in [Lists](/api-ref/lists) and [Saved Searches](/api-ref/saved-searches).
# Changelog
Source: https://api.tryspecter.com/api-ref/changes
New endpoints, fields and behaviour changes in the Specter API — newest first.
New endpoints, fields and behaviour changes in the Specter API — newest first. Use the tags to filter by product.
Bookmark this page for updates. If an update isn't clear or you need help planning a migration, email [api-support@tryspecter.com](mailto:api-support@tryspecter.com).
Breaking changes, effective 2026-09-30:
**`news` removed from the company object**
`news[]` carries Specter News v1 and is dropped from every endpoint that returns a company — [Get company by ID](/api-reference/companies/get-company-by-id), [Enrich company](/api-reference/enrich/enrich-company), [Enrich companies (bulk)](/api-reference/enrich/enrich-companies-bulk), and the search, list and saved-search endpoints.
Use [Get company news](/api-reference/companies/get-company-news) instead. It returns the full News v2 history, newest first, and adds `whats_new`, `meaningful_updates` and `score`. The v1 fields map as:
| `company.news[]` | [Get company news](/api-reference/companies/get-company-news) |
| ---------------- | ------------------------------------------------------------- |
| `date` | `published_date` |
| `title` | `title` (English), `title_original` (source language) |
| `url` | `article_url` |
| `publisher` | No equivalent; infer it from `article_url` |
**What you need to do:** replace reads of `company.news[]` with a call to the endpoint. It costs 1 credit per request, returning up to 50 results per page, where the v1 block came with the company response.
**Investor IDs on `funding.round_details`**
`funding.round_details[].investors` becomes an array of objects — `investor_id`, `investor_name`, `is_lead_investor` — instead of investor-name strings. That is the shape [Get company funding rounds](/api-reference/companies/get-company-funding-rounds) and [Get funding round by ID](/api-reference/transactions/get-funding-round-by-id) already return, and `investor_id` resolves through [Get investor by ID](/api-reference/investors/get-investor-by-id).
**What you need to do:** read `investor_name` where you read the string.
This is a big release. We've reorganised the API around a cleaner, more consistent set of endpoints, retired sixteen of the older ones, added ten new endpoints, and changed a number of prices and field names. Everything you need to act on is below.
**Sixteen endpoints are retired**
Fifteen have a drop-in replacement. The sixteenth, Text search, doesn't: [Search entities by name](/api-reference/search/search-entities-by-name) will resolve a name for you, but nothing replaces pulling entities out of free text. Repoint your calls and you're done; the retired paths now return `404`.
| Removed | Use instead |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Search company name | [Search entities by name](/api-reference/search/search-entities-by-name) |
| Search person name | [Search entities by name](/api-reference/search/search-entities-by-name) |
| Search investor name | [Search entities by name](/api-reference/search/search-entities-by-name) |
| Get similar companies | [Get company competitors](/api-reference/companies/get-company-competitors) |
| Bulk get similar companies by ID | [Get company competitors](/api-reference/companies/get-company-competitors) |
| Get news signal by ID | [Get company news](/api-reference/companies/get-company-news) |
| Get news signals for a company list | [Get company news](/api-reference/companies/get-company-news) |
| Get news signals for a saved company search | [Get company news](/api-reference/companies/get-company-news) |
| Get revenue signal by ID | [Get revenue signals by date](/api-reference/revenue-signals/get-revenue-signals-by-date) |
| Get revenue signals for a company list | [Get company revenue signals](/api-reference/companies/get-company-revenue-signals) |
| Get revenue signals for a saved company search | [Get company revenue signals](/api-reference/companies/get-company-revenue-signals) |
| Get talent signal by ID | [Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date) |
| Bulk get talent signals by ID | [Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date) |
| Get investor interest signal by ID | [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date) |
| Bulk get investor interest signals by ID | [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date) |
| Text search | No replacement |
**Ten new endpoints**
Ten new endpoints have been added:
| Endpoint | What it does |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [Find person ID](/api-reference/people/find-person-id) | The Specter `person_id` for a LinkedIn URL, vanity id, numeric id, or URN (batch, free) |
| [Find investor ID](/api-reference/investors/find-investor-id) | The Specter `investor_id` for a website or name (batch, free) |
| [Get acquisitions by date](/api-reference/transactions/get-acquisitions-by-date) | Acquisitions announced in a date range, across all companies |
| [Get funding rounds by date](/api-reference/transactions/get-funding-rounds-by-date) | Funding rounds announced in a date range, across all companies |
| [Get IPOs by date](/api-reference/transactions/get-ipos-by-date) | IPOs in a date range, across all companies |
| [Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date) | Talent-movement signals in a date range |
| [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date) | Investor-interest signals in a date range |
| [Get company investor-interest signals](/api-reference/companies/get-company-investor-interest-signals) | Investor-interest signals for one company |
| [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals) | Investor-interest signals for one investor |
| [Get person talent signals](/api-reference/people/get-person-talent-signals) | Talent signals for one person |
**Saved searches can be created, and cover the transaction products**
[Create saved search](/api-reference/saved-searches/create-saved-search) saves an existing query under a name. Pass the `query_id` that [AI search](/api-reference/search/ai-search) returns, plus a name. The search is assigned to an admin of your organisation and reports them as `owner_id`; only an admin-owned search can be deleted through the API. The product comes from the saved query rather than the request, and the search is shared with the API and your organisation on creation, so it is readable straight away. Free.
Until now a saved search could only be created in the app and shared from there, and the API could delete a search it had no way of making.
Saved searches for the three transaction products are now readable too, matching the five that already were:
| Product | Endpoints |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Funding rounds | [Get funding rounds saved search](/api-reference/funding-rounds-saved-searches/get-funding-rounds-saved-search), [results](/api-reference/funding-rounds-saved-searches/get-funding-rounds-saved-search-results) |
| Acquisitions | [Get acquisitions saved search](/api-reference/acquisitions-saved-searches/get-acquisitions-saved-search), [results](/api-reference/acquisitions-saved-searches/get-acquisitions-saved-search-results) |
| IPOs | [Get IPOs saved search](/api-reference/ipos-saved-searches/get-ipos-saved-search), [results](/api-reference/ipos-saved-searches/get-ipos-saved-search-results) |
Each results item is the same object the matching by-date feed returns, so it parses identically. Detail endpoints are free; results cost 1 credit per result returned.
**Company funding rounds name their company**
[Get company funding rounds](/api-reference/companies/get-company-funding-rounds) returns `company_id` and `company_name` on every row, matching [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds) and [Get funding rounds by date](/api-reference/transactions/get-funding-rounds-by-date). A row stays attributable once it is separated from the request that produced it. `investor_count` stays specific to the company-scoped endpoint.
**Get funding rounds by date schema corrected**
The reference documented [Get funding rounds by date](/api-reference/transactions/get-funding-rounds-by-date) with the company-scoped round shape, which carries `investor_count`. The endpoint returns the cross-company shape, which does not. The response itself has not changed, only its documentation.
**Pricing**
The following prices have changed:
| Endpoint | Was | Now |
| ----------------------------------------------------------------------------------------- | -------------------- | -------------------- |
| [Get company revenue signals](/api-reference/companies/get-company-revenue-signals) | 10 per signal | 2 per result |
| [Get revenue signals by date](/api-reference/revenue-signals/get-revenue-signals-by-date) | 10 per signal | 2 per signal |
| [AI search](/api-reference/search/ai-search) | 1 per result | 1 per 5 results |
| [Get person email](/api-reference/people/get-person-email) | 1 per email | 2 per matched result |
| [Enrich person by email](/api-reference/enrich/enrich-person-by-email) | 1 per request | 2 per matched result |
| [Enrich people by email (bulk)](/api-reference/enrich/enrich-people-by-email-bulk) | 1 per matched person | 2 per matched result |
**One page size, 50, on the paginated reads**
These endpoints charge one credit per request for a page of up to 50 results, and the page limit now matches that unit everywhere: previously up to 1000 ([Get company funding rounds](/api-reference/companies/get-company-funding-rounds), [Get company acquisitions](/api-reference/companies/get-company-acquisitions), [Get company IPOs](/api-reference/companies/get-company-ipos), [Get company news](/api-reference/companies/get-company-news), [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds), [Get network people](/api-reference/network/get-network-people), [Get network companies](/api-reference/network/get-network-companies)); previously up to 100 ([Get company employees](/api-reference/companies/get-company-employees)); previously up to 25, so these now return more per page ([Get acquisitions by date](/api-reference/transactions/get-acquisitions-by-date), [Get funding rounds by date](/api-reference/transactions/get-funding-rounds-by-date), [Get IPOs by date](/api-reference/transactions/get-ipos-by-date)); newly paginated ([Get network connections at a company](/api-reference/network/get-network-connections-at-a-company) pages its contacts, while `roles` and `connected_teammates` still describe the whole company).
Sending `limit` above 50 now returns `422` rather than a larger page. The default is unchanged at 50, so a caller that never set `limit` is unaffected; one that set it higher should drop to 50 and page with `page`.
**AI search costs one credit per 5 results**
[AI search](/api-reference/search/ai-search) is billed per 5 results returned, rounded up, instead of 1 credit per result. A full page of 50 costs 10 credits where those 50 results used to cost 50, three results cost 1, and a query that matches nothing costs nothing. Results are cached at the organisation level for 7 days, so an identical query from your team within that window returns the cached result. Pagination now works like the other paginated reads: 50 results a page, up from 25, walked with `page` and `limit`, with `X-Total-Count`, `X-Page`, `X-Page-Size`, `X-Total-Pages` and `Link` describing the position. `limit` above 50 returns a `422`, and paging a query returns the same result set throughout, so a record does not move between pages as you walk them.
**Poll a saved search from a moment you choose: `new_results_after`**
Every saved-search results endpoint accepts `new_results_after`, a timestamp such as `2026-07-10T00:00:00Z`. Results are then limited to the records added to that search on or after it, so a scheduled job passes back the timestamp of its last read and receives exactly what arrived in between, with no double-reads and no gap. All eight products support it: companies, people, investors, talent signals, investor-interest signals, funding rounds, acquisitions and IPOs. Additions are tracked for 60 days. A cutoff older than that returns `422` with `NEW_RESULTS_AFTER_BEYOND_RETENTION`, rather than an answer that silently omits pruned rows.
This deprecates `new`. The `new` flag restricted results to a fixed this-week window; `new_results_after` does the same job with a window you control, and takes precedence when both are sent. `new` is no longer documented anywhere in this reference: on the saved-search results endpoints, on [Get revenue signals by date](/api-reference/revenue-signals/get-revenue-signals-by-date), [Get company revenue signals](/api-reference/companies/get-company-revenue-signals) or [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date). Existing calls that send it keep working for now, but move them over: use `new_results_after` on a saved search, or the endpoint's `*_date_after` bound for a publication-date window.
**Request changes**
[Enrich company](/api-reference/enrich/enrich-company) accepts a new `pitchbook_url` identifier alongside `domain`, `website_url`, `linkedin_url`, `linkedin_id` and `crunchbase_url`. [Find company ID](/api-reference/companies/find-company-id) accepts `crunchbase_url` (an organisation profile) and `pitchbook_url`; both behave like `linkedin_url`, with exactly one identifier per entry, at most one match, and `match_confidence` 1, and both accept http/https, www, query strings and anchors. Still free.
[Get company acquisitions](/api-reference/companies/get-company-acquisitions) gains `acquired_date_after` / `acquired_date_before`, and [Get company funding rounds](/api-reference/companies/get-company-funding-rounds) gains `funding_announced_date_after` / `funding_announced_date_before`. Both bounds are inclusive.
[Get company competitors](/api-reference/companies/get-company-competitors) no longer accepts `refresh`. Freshness is decided internally: results older than 30 days are recomputed automatically. Sending `refresh` now returns `422`.
**`growth_stage` values now match the filter vocabulary**
The company object's `growth_stage` was serialised with its own display labels, while the `growth_stage` filter parameters accepted the underlying values, so the same field spoke two vocabularies depending on whether you were reading or filtering. The response now returns the same values the filters take:
| Was | Now |
| -------------- | ------------------------------ |
| `seed_stage` | `seed` |
| `early_stage` | `early` |
| `growth_stage` | `growing` |
| `late_stage` | `late` |
| `exit_stage` | `exit` |
| `bootstrapped` | `bootstrapped` or `no_funding` |
| `pre_launch` | `pre_launch` |
Two consequences worth noting: `bootstrapped` previously absorbed companies with no funding at all, which now report `no_funding` distinctly; and `pre_launch` was already being returned despite never appearing in the documented enum. If you match on `growth_stage` strings, map them using the table above. If you pass the value straight into a `growth_stage` filter, that now works without translation.
**Growth and funding highlights removed**
The deprecated highlight filters and their counts are gone from every endpoint that carried them. Removed query parameters: `newGrowthHighlights` and `newFundingHighlights` on [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results) and [Get company list results](/api-reference/company-lists/get-company-list-results). Removed response fields: `new_growth_highlights_count` and `new_funding_highlights_count` on [Get company saved search](/api-reference/company-saved-searches/get-company-saved-search) and [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches). `new_count` still reports companies first seen in a search.
**The bulk lookups are grouped with the enrichment endpoints**
Three bulk endpoints have moved into the Enrich group and been renamed to match what they do. Each accepts the same identifiers as its single-record enrich counterpart (a domain, website, LinkedIn URL and so on) and returns the same enriched records, just up to 50 per request, so they now sit alongside those endpoints under names that describe them.
| Was | Now |
| -------------------------- | ---------------------------------------------------------------------- |
| Get companies by ID (bulk) | [Enrich companies (bulk)](/api-reference/enrich/enrich-companies-bulk) |
| Get people by ID (bulk) | [Enrich people (bulk)](/api-reference/enrich/enrich-people-bulk) |
| Get investors by ID (bulk) | [Enrich investors (bulk)](/api-reference/enrich/enrich-investors-bulk) |
Paths, request bodies, responses and prices are unchanged, so there's nothing to do in your integration beyond updating your bookmarks.
**Enrichment context field renamed**
[Enrich person](/api-reference/enrich/enrich-person) returned its enrichment context timestamp as `updatedAt`, the one camelCase field on the API where every other field is snake\_case. It is now `updated_at`. The value and format are unchanged.
**People list entries are keyed `person_id`**
[Get people list](/api-reference/people-lists/get-people-list) names each entry's identifier in `people[]` as `person_id`, matching the `company_id` and `investor_id` its sibling endpoints already use. The old `people_id` key is gone.
**`raised_amount_usd` is a number on investor funds**
Each entry in an investor's `fund_details[]` returns `raised_amount_usd` as a JSON number rather than a string: `750000000`, not `"750000000"`. This affects every endpoint that returns an investor: [Get investor by ID](/api-reference/investors/get-investor-by-id), [Enrich investors (bulk)](/api-reference/enrich/enrich-investors-bulk), [Enrich investor](/api-reference/enrich/enrich-investor), [Get investor list results](/api-reference/investor-lists/get-investor-list-results) and [Get investor saved search results](/api-reference/investor-saved-searches/get-investor-saved-search-results). The funding round endpoints already returned a number here.
**`hq.region` is now `hq.continent`**
The `hq.region` deprecation announced on 2026-03-20 is enforced: the field is gone. `hq.continent` carries the same value from the same source, so the fix for a caller still reading `region` is a one-line rename. It applies everywhere an `hq` is returned: [Get company by ID](/api-reference/companies/get-company-by-id), [Find company ID](/api-reference/companies/find-company-id), [Search entities by name](/api-reference/search/search-entities-by-name), and the `company.hq` and `person.location` blocks on the investor-interest signal endpoints. `hq.regions`, the plural metro-area groupings such as `["San Francisco Bay Area", "United States"]`, is unchanged and stays specific to [Get company by ID](/api-reference/companies/get-company-by-id). It is a different field from the company's top-level `regions`, which carries a single country-level grouping.
**Company employees carry the full person record**
[Get company employees](/api-reference/companies/get-company-employees) returns each person's own profile alongside their role at the company: `first_name`, `last_name`, `profile_picture_url`, `linkedin_url`, `linkedin_num_id`, `twitter_url`, `github_url`, `tagline`, `location`, `region`, `highlights`, `talent_signal_ids` and `investor_signal_ids`. A team page that took one [Get person by ID](/api-reference/people/get-person-by-id) call per employee is now a single request. Follow `person_id` for the fields that stay profile-only: `experience`, `education`, `skills` and `languages`. The `region` here is the person's own region, independent of the company's `hq`.
**The by-email endpoints return the full person record**
[Enrich person by email](/api-reference/enrich/enrich-person-by-email) and [Enrich people by email (bulk)](/api-reference/enrich/enrich-people-by-email-bulk) return the same person object as [Get person by ID](/api-reference/people/get-person-by-id), plus the email each result resolved from and the match score. Every profile field is now included, so a match no longer needs a follow-up call. The seven-field summary these endpoints used to return is gone, and `company_id` is no longer a top-level key; a person's roles live in `experience[]`, each with its own `company_id`. Pricing is unchanged at 2 credits per matched result, and an unmatched address still returns `204` on the single endpoint and is still omitted from the bulk response.
**`is_global` and `shared_with` on lists**
The list endpoints return two new fields, on both the collection and the per-list response: `is_global`, which is true for lists curated by Specter, and `shared_with`, the Specter user IDs the list is shared with, or `[]` when it is not shared. Resolve an ID to a person with [Get organization members](/api-reference/account/get-organization-members). This applies to [Get all company lists](/api-reference/company-lists/get-all-company-lists), [Get company list](/api-reference/company-lists/get-company-list), [Get all people lists](/api-reference/people-lists/get-all-people-lists), [Get people list](/api-reference/people-lists/get-people-list), [Get all investor lists](/api-reference/investor-lists/get-all-investor-lists) and [Get investor list](/api-reference/investor-lists/get-investor-list). [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches) also carries `is_global`, which the per-product saved-search endpoints already returned.
**Smaller changes**
`website.domain_aliases` returns `[]` rather than `null` when a company has no alias domains, matching `organization_name_aliases`.
**What you need to do:** move off the sixteen retired paths using the table above, drop `refresh` from any competitors request, stop sending `newGrowthHighlights` / `newFundingHighlights` and stop reading the two `*_highlights_count` fields, read `context.updated_at` instead of `context.updatedAt` on enrich-person, drop any `limit` above 50 on AI search and on the per-entity paginated reads and page for more, stop sending `new` and use `new_results_after` or the endpoint's date bounds instead, read `person_id` instead of `people_id` on people list entries, parse `fund_details[].raised_amount_usd` as a number, read `experience[]` instead of the top-level `company_id` on the by-email endpoints, rename `hq.region` to `hq.continent`, and re-check your credit budgeting against the new prices, including the doubled email lookups.
Plan change:
**One API plan**
The Enrichment-only plan is retired. Every approved key now reaches the whole endpoint surface — the enrichment endpoints ([Enrich company](/api-reference/enrich/enrich-company), [Enrich person](/api-reference/enrich/enrich-person), [Enrich investor](/api-reference/enrich/enrich-investor)) alongside the databases, signals, saved searches, lists, and network endpoints.
No migration is needed. No key was provisioned on the Enrichment-only plan, so every call that worked before behaves identically. See [Plans & Pricing](/api-ref/plans).
New endpoints:
**Get credit balance**: [`GET /organization/credits`](/api-reference/account/get-credit-balance)
Read your organization's credit position for the current billing window without contacting support: `credit_limit`, `used`, `remaining`, and `unlimited`. A `credit_limit` of `-1` means unlimited. The endpoint is **free**, and it stays readable when your balance is exhausted, so you can always check where you stand, even after a `402`.
**Search entities by name**: [`GET /entities/search`](/api-reference/search/search-entities-by-name)
One name search across companies, people, and investors, returning basic records grouped by entity type. Pass `types` to narrow the search and `limit` (1–50) to cap matches per type. Also **free**.
This replaces the three per-entity name searches, which are being retired: `GET /companies/search`, `GET /people/search`, and `GET /investors/search`. Migrate to `GET /entities/search`: it covers all three in one call and costs nothing.
Breaking change:
**Deprecated industry taxonomy removed**
The legacy `industries` and `sub_industries` fields are no longer returned by any endpoint. They were superseded by `industry` (the Specter v2 taxonomy) and `tech_verticals`, both of which have been returned alongside them for some time.
**What you need to do:** read `industry` instead of `industries`, and `tech_verticals` instead of `sub_industries`. If you mapped the legacy values yourself, note that the v2 taxonomy is not a one-to-one renaming, so review the values you depend on.
**`is_global` on company saved searches**
[Get company saved search](/api-reference/company-saved-searches/get-company-saved-search) now returns `is_global`, matching the investor, people, talent and investor-interest saved-search endpoints and the generic [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches). It is `true` for global searches curated by Specter and `false` for searches owned by your organization.
Breaking change:
**Company response**
The `ipo[]` block on the company object is now serialised in snake\_case, keyed exactly like the IPO endpoints ([Get company IPOs](/api-reference/companies/get-company-ipos), [Get IPO by ID](/api-reference/transactions/get-ipo-by-id)). The camelCase keys are no longer returned.
| Old key | New key |
| ---------------- | ----------------------- |
| `wentPublicOn` | `went_public_on` |
| `stockExchange` | `stock_exchange_symbol` |
| `stockSymbol` | `stock_symbol` |
| `sharePrice` | `share_price_usd` |
| `valuationPrice` | `valuation_price_usd` |
| `raisedAmount` | `money_raised_usd` |
The values are unchanged: these amounts were already in USD, and the `_usd` suffix now says so. This was the last camelCase block in the API; every response field is snake\_case from here.
**What you need to do:** update any integration that reads a key from `company.ipo[]` to the new name in the table above.
Correction:
**Enrich companies (bulk)**
[`POST /companies/by-id/bulk`](/api-reference/enrich/enrich-companies-bulk) returns a bare JSON array of company objects, the same schema as [Enrich company](/api-reference/enrich/enrich-company). Identifiers that don't match a known company are silently omitted from the response. This corrects the 2026-06-09 entry below, which described each row as a `{ status, company, enrichment }` wrapper; no such wrapper exists. Update any integration that reads a per-row `status` field.
New endpoints:
### Account
[`GET /health`](/api-reference/account/health-check): returns `200 {"status":"OK"}` while the API is up and able to reach its backing databases. Unauthenticated and free.
`GET /logs` entries now include two new fields: `credits_consumed` (the number of credits the call drew from your plan, or `null` if not known; older rows aren't backfilled) and `request_id` (a UUID matching the `X-Request-ID` response header, useful when contacting support about a specific call).
Breaking change:
**AI search**
The [AI search](/api-reference/search/ai-search) `resource_type` parameter has been renamed to `product`, in both the request body and the response. The enum values are unchanged. Update any integration that sends or reads `resource_type` to use `product`.
New filters:
The following endpoints now accept explicit date-range query parameters, named after the date each object is keyed on. Both bounds are inclusive of the given calendar day (`YYYY-MM-DD`) and can be combined:
* [Get revenue signals by date](/api-reference/revenue-signals/get-revenue-signals-by-date), [Get company revenue signals](/api-reference/companies/get-company-revenue-signals) and Get Revenue Signals for a saved company search — `revenue_signal_date_after` / `revenue_signal_date_before`. When both `new` and `revenue_signal_date_after` are given, the explicit date wins.
* [Get company news](/api-reference/companies/get-company-news) and Get News Signals for a saved company search — `news_publication_date_after` / `news_publication_date_before`.
* [Get talent signal saved search results](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search-results) — `talent_signal_date_after` / `talent_signal_date_before`.
* [Get investor-interest saved search results](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search-results) — `investor_signal_date_after` / `investor_signal_date_before`.
* [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds) — `funding_announced_date_after` / `funding_announced_date_before`.
New endpoints:
**AI search**
[AI search](/api-reference/search/ai-search) turns a natural-language query into a structured search across all products and returns matching records. Set `product` to target a specific product, or leave it empty to let the API infer it. Results use the same format as other endpoints and support `page`/`limit` pagination.
Costs 1 credit per result; use `limit=1` to check `total_count` before fetching more. User-scoped filters (network, CRM, saved lists) aren't supported and will return a `422` error.
New endpoints:
**Companies**
* [Find company ID](/api-reference/companies/find-company-id) — resolves a batch of alternate identifiers (domain, website, LinkedIn URL, or company name) into the Specter company `id`, so you can then call the id-only company endpoints (revenue, valuation, people, …) without knowing the Specter ID upfront. Send up to 50 identifiers under `to_resolve` and get one result group per input, in order. Exact identifiers return a single match; a name is fuzzy-matched and returns up to 10 ranked candidates. Free — no credits are charged.
* [Get company competitors](/api-reference/companies/get-company-competitors) — returns the competitive landscape for a company: a ranked list of competitors, the dimensions the market splits on, and a summary of the landscape. The optional request body accepts `limit` (1–30, default 30) and `refresh` (default `false`). It's cache-first — an already-analysed company returns instantly, while a cold company (or `refresh: true`) computes the landscape on demand; results older than 30 days are recomputed automatically, and `last_updated` reports when it was last computed. Costs 1 credit per request.
**Revenue Signals**
* [Get company revenue signals](/api-reference/companies/get-company-revenue-signals) — returns a single company's full revenue (and profitability) signal history in reverse chronological order (most recent first), identified by its Specter company ID. Supports `limit`/`page` pagination and a `new` toggle that restricts results to signals published in the current week. Returns `404` when the company is unknown; a known company with no signals returns a 200 with an empty array. Costs 10 credits per signal returned.
Removed fields:
**Company response**
* `revenue_estimate_usd` has been removed from the company object. This field carried an estimated annual revenue band that was almost always `null`, and is no longer returned by any endpoint that includes a company.
**What you need to do:** if your integration reads `company.revenue_estimate_usd`, stop relying on it.
New endpoints:
**Companies**
* [Get company latest revenue](/api-reference/companies/get-company-latest-revenue) — returns the latest revenue figures and estimated revenue growth for a single company, by Specter company ID. Includes the estimated and last-reported revenue (with its reported metric type) plus estimated revenue growth across 1-month to 2-year windows. Costs 1 credit per request.
* [Get company latest valuation](/api-reference/companies/get-company-latest-valuation) — returns the latest valuation figures and estimated valuation growth for a single company, by Specter company ID. Includes the estimated and last-reported post-money valuation plus estimated valuation growth across 1-month to 2-year windows. Costs 1 credit per request.
New endpoints:
**Revenue Signals**
* Get Revenue Signal by ID — retrieve a single revenue (or profitability) signal by its Specter signal id (`rev_...`). Each signal corresponds to one observation derived from news coverage or a public filing — the revenue (or profitability) figures, the year they refer to, the source URL, and the company they are attributed to.
* [Get revenue signals by date](/api-reference/revenue-signals/get-revenue-signals-by-date) — list revenue (and profitability) signals, newest first. Each item is the same signal object returned by Get Revenue Signal by ID.
* Get Revenue Signals for a company list — returns every revenue signal attributed to the companies in a given list, newest first. Companies outside the list are excluded. Lists with more than 5,000 member companies are capped at that limit; unknown or non-visible lists return `404`.
* Get Revenue Signals for a saved company search — returns every revenue signal attributed to the companies returned by a saved company search, newest first. Date-range queries live inside the saved search itself. Searches matching more than 5,000 companies are capped at that limit; unknown or non-visible searches return `404`.
Behavior common to both:
* `new=true` restricts the results to signals published in the current week.
* Supports `limit`/`page` pagination.
* These endpoints use 10 credits per signal returned.
**Credit-limit responses now return 402**
Running out of credits now returns HTTP `402` instead of HTTP `429`, so you can distinguish being credit‑limited from being rate‑limited:
* `402` with errorCode `OUT_OF_CREDITS` — your team has no credits left for the current billing period. The response carries the `X-CreditLimit-*` headers, including `X-CreditLimit-Reset` with the seconds until credits renew.
* `429` with errorCode `RATE_LIMITED` — unchanged; you sent too many requests per second.
**What you need to do:** if your integration treats `429` as "out of credits", update it to handle `402` for that case. Retry-on-429 logic can stay as is.
**Bulk Endpoints**
New endpoints — bulk variants of the existing lookup and enrichment endpoints. Each accepts up to 50 identifiers in a single request, so you can resolve many records in one call instead of issuing them one at a time. For lookup endpoints, unknown identifiers are silently omitted; for enrichment endpoints each row carries a found/queued status (see the entry). Each uses 1 credit per record returned (misses/queued rows are not charged).
**Enrichment**
* [Enrich companies (bulk)](/api-reference/enrich/enrich-companies-bulk) — bulk counterpart to [Enrich company](/api-reference/enrich/enrich-company); resolve companies by website, domain, LinkedIn URL/ID, or Crunchbase URL. Each row carries a status of found (with the company payload) or queued (an enrichment was started for an unknown company); only found rows are charged.
* [Enrich people (bulk)](/api-reference/enrich/enrich-people-bulk) — bulk counterpart to [Enrich person](/api-reference/enrich/enrich-person); resolve people by LinkedIn URL/ID/URN. Each row carries a status of found (with the person payload) or queued (async enrichment started); only found rows are charged.
* [Enrich people by email (bulk)](/api-reference/enrich/enrich-people-by-email-bulk) — bulk counterpart to [Enrich person by email](/api-reference/enrich/enrich-person-by-email); reverse-lookup people from email addresses.
**Companies**
* Get similar companies (bulk) — bulk counterpart to Get similar companies; find lookalike companies for multiple seed company IDs at once.
**Investors**
* [Enrich investors (bulk)](/api-reference/enrich/enrich-investors-bulk) — look up investors by website or name.
**Talent and Interest Signals**
* Bulk get Talent Signals by ID — bulk counterpart to Get Talent Signal; fetch talent signals by ID. Duplicate IDs are honored.
* Bulk get Investor Interest Signals by ID — bulk counterpart to Get Investor Interest Signal by ID; fetch investor interest signals by ID. Duplicate IDs are honored.
**Name based search for companies, people and investors**
Name-based search across companies, people and investors. Each search endpoint takes a required `query` string (minimum 3 characters), returns up to 10 lightweight results sorted by descending `match_confidence`, and uses 1 credit per request regardless of how many matches come back. Chain the corresponding `GET /{id}` endpoint on any result for the full profile.
**People search**
* Search person name — fuzzy search for people by name. Returns up to 10 candidates, each with `id`, `full_name`, `headline`, `linkedin_url`, `profile_picture_url`, `current_company_name`, and a `match_confidence`. Only matches scoring at least 0.5 are returned; no match returns an empty list. This is a catalogue search and never triggers enrichment — to enrich a brand new LinkedIn identifier, keep using [Enrich person](/api-reference/enrich/enrich-person).
**Investor search**
* Search investor name — fuzzy search for investors by name. Returns up to 10 candidates, each with `id`, `name`, `domain`, `hq_location`, `founded_year`, `type`, and a `match_confidence`. Only matches scoring at least 0.5 are returned. [Enrich investor](/api-reference/enrich/enrich-investor) (lookup by website / exact name) is unchanged.
**Company search**
* Search company name now returns a `match_confidence` on every result and applies the same 0.5 threshold, so weak matches no longer appear.
**A note on match\_confidence**
All three endpoints expose `match_confidence` on a 0–1 scale, but they are derived differently. Investor search uses trigram similarity, which is absolute — scores are comparable across separate calls. People and company search scores are relative to the results within a single response and should not be compared between calls.
New endpoints:
**Network Mapping**
Three new endpoints expose your team's LinkedIn network — the people your teammates are connected to, deduped across the team, and the companies they work at. Use them to find a warm path into a target company or to surface who on your team already knows a given contact.
* [Get network people](/api-reference/network/get-network-people) — returns all people your team is connected to on LinkedIn, deduped across teammates. Each result includes which teammates hold the connection. Supports `limit`/`page` pagination and a `connected_on` filter (only `linkedin` is supported today).
* [Get network companies](/api-reference/network/get-network-companies) — returns all companies where someone in your team's network currently works, ordered by number of connections at each company. Each result includes the person IDs of your contacts there. Supports `limit`/`page` pagination and a `min_connections` filter to only return companies with at least that many network contacts.
* [Get network connections at a company](/api-reference/network/get-network-connections-at-a-company) — returns your team's connections at a specific company: who you know there, what roles they hold, and which teammates are linked to them. Returns `404` when your team has no connections at the requested company.
Each endpoint uses 1 credit per request.
**Organization**
* [Get organization members](/api-reference/account/get-organization-members) — returns all active members of your team: their user ID, role (admin or member), name, and email. Suspended users are excluded. Supports `limit`/`page` pagination. The `user_id` field matches the `connected_teammates` values returned by the Network endpoints, so you can use it to resolve teammate IDs back to a named person. This endpoint uses 1 credit per request.
New endpoints:
**News Signals**
* Get News Signal by ID — retrieve a single news signal by its integer Specter signal id. A news signal represents one classified company mention within a single article; when an article mentions multiple companies, each company yields its own signal.
* [Get company news](/api-reference/companies/get-company-news) — returns a company's full news signal history in reverse chronological order (most recent first). Supports `limit`/`page` pagination and a `major_only` toggle that restricts results to signals with importance score ≥ 4.
Each signal includes the underlying article (id, URL, title, published date, featured image), the kinds of `meaningful_updates` detected (revenue, profitability, traction, funding, deals), an AI-generated summary of what's new, and an importance score on a 0–5 scale.
New endpoints:
**Investor lookup**
* [Enrich investor](/api-reference/enrich/enrich-investor) — look up Specter investor records by `website` and/or `name` query parameters. Returns the matching investor records with full detail (profile, activity, targeting, funds, portfolio companies). Use it to resolve an inbound mention of an investor — a domain on a deck, a firm name in a press release — to the canonical Specter ID for downstream calls.
Behavior:
* The endpoint returns a list of investors. A lookup can match more than one investor (e.g. multiple firms sharing a domain), so the endpoint returns all matches.
* When no investor matches, the response is `404 Not Found`.
* Query parameters: provide at least one of `website` or `name`. Supplying both narrows the match. Missing both returns `422`.
New endpoints:
**Investors**
* [Get investor by ID](/api-reference/investors/get-investor-by-id) — returns the full Specter investor record for a single investor ID, including profile, targeting, funds, and portfolio companies. Useful for enriching a known investor, pulling portfolio company IDs for downstream calls, or inspecting targeting (industries, verticals, stages) before outreach.
**Investor saved searches**
* [Get investor saved search](/api-reference/investor-saved-searches/get-investor-saved-search) — returns the name, query ID, and total matched-investor count for a saved investor search. Use it to confirm a search is bound to the expected query, or to surface counts in a UI without fetching results.
* [Get investor saved search results](/api-reference/investor-saved-searches/get-investor-saved-search-results) — returns the investors matching a saved investor search with full detail (profile, activity, targeting, funds, portfolio companies). Supports `limit` (default 50, max 5000) and `page` (0-indexed).
**Investor lists**
* [Get all investor lists](/api-reference/investor-lists/get-all-investor-lists) — returns all investor lists created with the API, shared with the API, or shared globally, including the count of investors in each list.
* [Create investor list](/api-reference/investor-lists/create-investor-list) — create a new investor list.
* [Get investor list](/api-reference/investor-lists/get-investor-list) — retrieve details of a specific investor list, including the investor IDs it contains.
* [Update investor list](/api-reference/investor-lists/update-investor-list) — modify an existing investor list.
* [Delete investor list](/api-reference/investor-lists/delete-investor-list) — delete an investor list.
* [Get investor list results](/api-reference/investor-lists/get-investor-list-results) — returns the investors in a specific list along with their current profile, activity, and targeting data. The list must be of product type investors and must be shared with the API or created by the API.
**Transactions**
Three new typed resources cover the company-level transaction history — funding rounds, acquisitions, and IPOs — that used to require bulk delivery. Use these to look up a transaction referenced from another API response, audit an investor's recent activity, or stitch a company's funding history into your CRM without round-tripping through bulk exports.
Funding rounds:
* [Get funding round by ID](/api-reference/transactions/get-funding-round-by-id) — a single round with its raising company and full investor list (lead flagged).
* [Get company funding rounds](/api-reference/companies/get-company-funding-rounds) — paginated funding history for one company.
* [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds) — paginated list of rounds an investor has participated in.
Acquisitions:
* [Get acquisition by ID](/api-reference/transactions/get-acquisition-by-id) — a single acquisition with acquirer and acquiree context.
* [Get company acquisitions](/api-reference/companies/get-company-acquisitions) — acquisitions where the given company is the acquirer.
IPOs:
* [Get IPO by ID](/api-reference/transactions/get-ipo-by-id) — a single IPO with the issuing company, exchange and ticker symbol, listing date, and proceeds in USD.
* [Get company IPOs](/api-reference/companies/get-company-ipos) — IPOs by company.
New endpoints:
**API Call Logs**
* [Get API call logs](/api-reference/account/get-api-call-logs) — returns a paginated list of API calls made by your organization, ordered by most recent first. Use it to audit which endpoints your integration is hitting, debug failed calls by inspecting HTTP status codes and paths, and monitor usage trends across your team.
Parameters:
* `limit` / `page` — pagination controls
* `from` / `to` — date range filter for log entries
Response fields per entry:
* `timestamp` — UTC timestamp of the call
* `path` — request path (e.g. `/v1/companies`)
* `url` — full URL including query string
* `http_method` — HTTP verb used
* `http_status` — HTTP status code returned
* `status` — logical status (`ok` or `error`)
* `query` — query parameters sent with the request (nullable)
New parameters:
**Talent search results & Investor Interest search results**
Both endpoints now accept a `new` query parameter (boolean, default false). When set to true, results are restricted to signals from the current week, overriding any `SignalDate` filter that is stored in the saved search. This is equivalent to applying a "This week" signal date filter without modifying the saved search itself — useful for polling integrations that always want the latest batch of signals.
Affected endpoints:
* [Get talent signal saved search results](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search-results)
* [Get investor-interest saved search results](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search-results)
New fields:
**Company response**
* Pitchbook URL — `company.socials.pitchbook.url`
* Crunchbase URL — `company.socials.crunchbase.url`
* HQ regions — `company.hq.regions`
* HQ continent — `company.hq.continent`
* Glassdoor data — `company.glassdoor`
* Glassdoor rating metrics — `company.traction_metrics.glassdoor_rating`
* Glassdoor reviews metrics — `company.traction_metrics.glassdoor_reviews`
**Talent response**
* Signal Summary — `talent.signal_summary`
* Experience Industry — `talent.experience[].industry`
* Experience Tech Verticals — `talent.experience[].tech_verticals`
* New position industry — `talent.new_position_industry`
* New position tech verticals — `talent.new_position_tech_verticals`
* Is new position industry estimated — `talent.is_new_position_industry_estimated`
**Investor Interest response**
* Signal Summary — `investor_interest.signal_summary`
* Person Industry — `investor_interest.person.industry`
* Person Tech Verticals — `investor_interest.person.tech_verticals`
* Person Is industry estimated — `investor_interest.person.is_industry_estimated`
* Company Industry — `investor_interest.company.industry`
* Company Tech Verticals — `investor_interest.company.tech_verticals`
* Company Is industry estimated — `investor_interest.company.is_industry_estimated`
* Company Customer Focus — `investor_interest.company.customer_focus`
Deprecated fields:
**Company response**
* HQ region — move to `company.hq.continent`.
Features:
**Enrich/Get Person**
* People can now be retrieved via the `linkedin_num_id` and the `linkedin_urn`.
New fields:
**Person responses**
* `linkedin_urn` — the URN of the person being returned, can be empty.
New fields:
**Person responses**
* `linkedin_num_id` — can be used to link a person to a URN.
* `last_updated` — a timestamp of when the person was last updated in the Specter dataset.
New endpoints:
**Enrich person by email**
* [Enrich person by email](/api-reference/enrich/enrich-person-by-email) — when you have an email address and need to resolve it to a Specter person record so you can standardize contacts, enrich them, or link inbound emails to the correct individual in our database.
**Resolve entity from text**
* `POST /entities/text-search` — turn unstructured text (press releases, bios, notes) into structured entity references you can track, enrich, and join to your downstream systems.
New endpoints added that give the ability to query for investor interest signals.
New endpoint added which gives the ability to Search company name and get back basic information for them given a query term.
Two new fields have been added to all endpoints which return companies.
* `founders_info` — gives more information about the founders including the `specter_person_id` which allows for the person to be looked up either in the App, or via the People API.
* `specter_strategic_signal_ids` — which indicate strategic signals related to the company.
* Added a new filter to the [Get company employees](/api-reference/companies/get-company-employees) endpoint allowing anyone that is a CEO to be returned. This new filter can only be used on its own and founders and department won't be taken into account with this filter.
* Updated all search and list endpoints to work with a new Share to API toggle. This allows lists and searches to be shared with the API without sharing them with the team.
A new endpoint for [Get person email](/api-reference/people/get-person-email) has been released which allows you to retrieve the professional or personal email address for a person based on their ID.
* Added endpoints for enrichment of people, which will notify us if there are people we do not have so we can retrieve them.
* Added endpoints for People and Talent Signals, allowing you to manage and get both using the API.
Added Get similar companies which returns a list of ids for companies that are similar to the company id being requested. This helps you uncover high-potential companies similar to the one you're referencing and is a powerful way to identify new opportunities, uncover competitors, or expand your investment pipeline with minimal effort.
First release of the API including:
* **Enrichment API** — querying to get companies based on parameters (LinkedIn URL, LinkedIn ID, domain, etc.).
* **Companies API** — get companies by Specter ID or list, and manage lists.
* **Searches API** — get all available searches and query for companies by search ID.
# Enrichment
Source: https://api.tryspecter.com/api-ref/enrichment
Resolve a company, person, or investor from a domain, LinkedIn URL, or email and return their full Specter profile.
Enrichment resolves a company, person, or investor from an identifier you already have (a domain, LinkedIn URL, or email) and returns their full Specter profile. If Specter doesn't already hold the record, enrichment fetches it on demand.
## Data categories
Enrichment returns the same profile object the entity's own endpoints return, so you parse it identically. What comes back depends on the entity:
**Company** (via [Enrich company](/api-reference/enrich/enrich-company) and [Enrich companies (bulk)](/api-reference/enrich/enrich-companies-bulk))
* **Profile & classification.** Name, description, HQ, founding year, operating status, industry, tech verticals, business model, and customer focus.
* **Funding & financials.** Funding history, rounds, investors, and post-money valuation.
* **Headcount & growth.** Employee count, department and location breakdowns, founders, and web-traffic and engagement traction.
* **Web & social.** Domain, website, social presence, and product reviews (G2, Trustpilot, Glassdoor).
**Person** (via [Enrich person](/api-reference/enrich/enrich-person), [Enrich people (bulk)](/api-reference/enrich/enrich-people-bulk), [Enrich person by email](/api-reference/enrich/enrich-person-by-email), and [Enrich people by email (bulk)](/api-reference/enrich/enrich-people-by-email-bulk))
* **Profile.** Name, tagline, about, location, and LinkedIn follower and connection counts.
* **Career history.** `experience[]`: companies, titles, tenure, and progression.
* **Education.** `education[]`: institutions, degrees, and fields of study.
* **Skills & attributes.** Skills, languages, seniority, and years of experience.
* **Social links.** LinkedIn, Twitter, and GitHub URLs.
**Investor** (via [Enrich investor](/api-reference/enrich/enrich-investor) and [Enrich investors (bulk)](/api-reference/enrich/enrich-investors-bulk))
* **Profile & classification.** Name, description, HQ, founding year, organisation size, investor types, investment stage, and industry / tech-vertical targeting.
* **Fund details.** Named funds with announce date and amount raised (`fund_details`).
* **Investment activity.** Number of investments, lead investments, exits, and funds.
* **Portfolio & linkages.** Backed companies (`portfolio_companies`), plus `person_id` / `company_id` linkages.
Verified contact details (a person's email) aren't part of the base person profile; retrieve them separately with [Get person email](/api-reference/people/get-person-email).
## Endpoints
| Method | Endpoint | Returns |
| ------ | ---------------------------------------------------------------------------------- | ---------------------------------------- |
| `POST` | [Enrich company](/api-reference/enrich/enrich-company) | A company by domain or website |
| `POST` | [Enrich companies (bulk)](/api-reference/enrich/enrich-companies-bulk) | Enrich up to 50 companies in one request |
| `POST` | [Enrich person](/api-reference/enrich/enrich-person) | A person by name, company, or LinkedIn |
| `POST` | [Enrich people (bulk)](/api-reference/enrich/enrich-people-bulk) | Enrich up to 50 people in one request |
| `GET` | [Enrich investor](/api-reference/enrich/enrich-investor) | An investor by name or domain |
| `POST` | [Enrich investors (bulk)](/api-reference/enrich/enrich-investors-bulk) | Enrich up to 50 investors in one request |
| `POST` | [Enrich person by email](/api-reference/enrich/enrich-person-by-email) | Resolve a single email to a person |
| `POST` | [Enrich people by email (bulk)](/api-reference/enrich/enrich-people-by-email-bulk) | Resolve up to 50 emails in one request |
## How to use the API
1. **Pick the endpoint for the identifier you hold.** A domain or website goes to [Enrich company](/api-reference/enrich/enrich-company); a name, company, or LinkedIn URL to [Enrich person](/api-reference/enrich/enrich-person); a name or domain to [Enrich investor](/api-reference/enrich/enrich-investor); an email address to [Enrich person by email](/api-reference/enrich/enrich-person-by-email).
2. **Send the identifier.** For example, enrich a company by its domain:
```bash theme={null}
curl --request POST \
--url https://app.tryspecter.com/api/v1/companies \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{ "domain": "tryspecter.com" }'
```
3. **Go bulk when you have many.** Every single-record endpoint has a bulk counterpart that takes up to 50 lookups per request: [Enrich companies (bulk)](/api-reference/enrich/enrich-companies-bulk), [Enrich people (bulk)](/api-reference/enrich/enrich-people-bulk), [Enrich investors (bulk)](/api-reference/enrich/enrich-investors-bulk), and [Enrich people by email (bulk)](/api-reference/enrich/enrich-people-by-email-bulk). Post a JSON array instead of a single object:
```bash theme={null}
curl --request POST \
--url https://app.tryspecter.com/api/v1/companies/by-id/bulk \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '[{ "domain": "stripe.com" }, { "domain": "revolut.com" }]'
```
4. **Read the matches.** Results come back as the same records the entity's own endpoints return; a miss returns no record.
## Notes
* If enrichment returns nothing, Specter doesn't hold the record yet and will begin gathering it; retry later.
* Every bulk endpoint is capped at 50 lookups per request and takes a JSON array; the single-record endpoints take one object.
* [Enrich people (bulk)](/api-reference/enrich/enrich-people-bulk) returns one row per lookup in input order, each carrying a `status` of `found` or `queued`; `queued` means Specter didn't hold the person yet and has started gathering them, so poll later. The other bulk endpoints omit misses instead, so a response can be shorter than the array you sent and its order isn't guaranteed.
* [Enrich companies (bulk)](/api-reference/enrich/enrich-companies-bulk) accepts one identifier per lookup object (website, domain, LinkedIn, or Crunchbase) and [Enrich people (bulk)](/api-reference/enrich/enrich-people-bulk) one LinkedIn identifier; [Enrich investors (bulk)](/api-reference/enrich/enrich-investors-bulk) takes a `website` and/or a `name`, and supplying both narrows the match.
* [Enrich person by email](/api-reference/enrich/enrich-person-by-email) and [Enrich people by email (bulk)](/api-reference/enrich/enrich-people-by-email-bulk) return the same person object as [Get person by ID](/api-reference/people/get-person-by-id), plus the email each result resolved from and the match score. A person's roles live in `experience[]`, each with its own `company_id`; there is no top-level `company_id`.
* For the exact credit cost, see each endpoint's own "Costs ..." note; enrichment is charged per matched result, so misses are free. A bulk call costs the same per match as its single-record counterpart, and `queued` rows aren't charged.
# Errors
Source: https://api.tryspecter.com/api-ref/errors
Every error is JSON with a machine-readable code and a human-readable fix; here's how to handle each one.
All errors return JSON with a consistent structure:
```json theme={null}
{
"errorCode": "API_KEY_MISSING",
"message": "No API Key was presented on the header X-API-KEY"
}
```
* `errorCode`. Machine-readable
* `message`. Human-readable explanation
## Status codes
| Code | Meaning | What to do |
| ----- | ------------------------------------------- | ----------------------------------------------------------------- |
| `400` | Bad request | Fix the request (invalid or missing parameters) |
| `401` | Unauthenticated | Send a valid API key in `X-API-Key` (not `Authorization: Bearer`) |
| `402` | Out of credits, or your daily limit reached | Stop; read `errorCode` for which — see below |
| `403` | Forbidden | Endpoint not included in your plan |
| `404` | Not found | Check the ID or resource |
| `422` | Validation error | Fix request based on `message` |
| `429` | Rate limited | Wait and retry |
| `5xx` | Server error | Retry with backoff |
## The two `402`s
A `402` is always "stop", but which ceiling stopped you decides what to do next:
| `errorCode` | Meaning | What to do |
| -------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `OUT_OF_CREDITS` | Your monthly credit budget is spent | Wait for the period to renew, or ask for more credits |
| `DAILY_CREDIT_CAP_REACHED` | Your organization's own daily limit is reached | Resume after 00:00 UTC; `X-CreditLimit-Daily-Reset` gives the wait in seconds. An admin can raise or remove the limit in the API console |
See [Rate Limits & Credit Limits](/api-ref/rate_limits) for both ceilings and the headers they report on.
## Retry rules
* **Retry only:** `429` and `5xx`
* **Do not retry:** `400`, `401`, `403`, `404`, `422`
* **Stop on:** `402` (either ceiling reached)
### Backoff strategy
* On `429` → wait for `X-RateLimit-Reset`
* On `5xx` → retry with exponential backoff (start \~1s, max 3–5 attempts)
## Request IDs
Every response — success or error — carries an `X-Request-ID` header uniquely
identifying that request:
```
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
```
When something goes wrong and the `message` alone doesn't explain it, include
this ID in your report to [api-support@tryspecter.com](mailto:api-support@tryspecter.com).
It lets us trace the exact request through our logs and diagnose the issue on our
side.
Send your own `X-Request-ID` on the request and we echo it back on the
response, so you can correlate it with your own logs. If you don't send one, we
generate it for you.
## Notes
* `404` = resource doesn't exist
* Empty results (`200` + `[]`) = valid, but no data
* `400` and `5xx` are not charged
* Per-result endpoints only charge for data returned
# Welcome to the Specter API
Source: https://api.tryspecter.com/api-ref/introduction
Specter is a private-markets intelligence platform that provides structured data and proprietary signals on companies, people, investors, transactions, and real-time signals like revenue, investor interest, and talent movement.
More than 300 firms rely on Specter, including venture and corporate VC teams sourcing deals, private equity firms tracking targets, recruiters mapping talent, and B2B sales teams identifying accounts.
companies
people
investors
transactions
The Specter API spans enrichment, core data, signals, and your team's network, plus the workflows that find and pull them (lists, saved searches, and AI search) and the account endpoints for usage and team data.
## Core Data
The foundational entities you can search, enrich, and expand:
Firmographics, funding, headcount, growth, and historical data.
Professional profiles, career history, and contact information.
Funds and angels, including investment focus, activity, and portfolios.
Funding rounds, acquisitions, and IPOs.
Each entity has a stable ID and is designed to link seamlessly across the system, enabling traversal between companies, people, investors, and transactions.
## Signals
Time-based insights that capture change, momentum, and intent:
Career moves, stealth activity, and leadership changes.
Which investors are tracking which companies, and how strongly.
Real-time indicators of company revenue and growth momentum.
Real-time detection of company-relevant news and events.
Signals are designed for monitoring, alerting, and powering real-time workflows on top of the underlying data.
## Network Mapping
Your team's LinkedIn relationship graph.
Everyone your team is connected to on LinkedIn, deduplicated across teammates.
Where those contacts work, ranked by how many you know there.
Who you know at a target company, their roles, and which teammates are linked.
Use it to find a warm path into a target account, or see who already knows a given contact.
## Workflows
Ways to find records and pull them in bulk, not one at a time.
Resolve a company, person, or investor from a domain, LinkedIn, or email.
Curated sets of companies, people, or investors you pull on demand.
Turn a search you've saved in the app into a live API feed.
Query every product in plain English.
You can create saved searches and lists in the web app or directly via the API. If you create them in the web app, you need to explicitly share them with the API before the API can see them.
## Account
Team and usage data for your workspace.
Your active team roster, to resolve teammate IDs back to named people.
Audit recent calls, their status, and the credits each one consumed.
To read your remaining allowance programmatically, call [Get credit balance](/api-reference/account/get-credit-balance). It's free, and it stays readable when your balance is exhausted.
## Make your first call
Every request carries your team's key on the `X-API-Key` header. This example calls [Enrich company](/api-reference/enrich/enrich-company) to look up a company by its domain:
```bash theme={null}
curl --request POST \
--url https://app.tryspecter.com/api/v1/companies \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{ "domain": "tryspecter.com" }'
```
A match comes back as JSON. The [Quickstart](/api-ref/quickstart) walks you from API key to your first result.
**Access is approval-based.** There's no self-serve signup. Request an API key via the [API Console](https://app.tryspecter.com/settings/api-console); approvals are typically granted within one business day. Usage is metered in credits. See [Plans & Pricing](/api-ref/plans) for details.
## Where to go next
Request to first result in four steps.
API keys, the X-API-Key header and credits.
The core data product and its endpoints.
Questions or feedback: [api-support@tryspecter.com](mailto:api-support@tryspecter.com).
# Lists
Source: https://api.tryspecter.com/api-ref/lists
Curated sets of companies, people, or investors
Lists are curated sets of companies, people, or investors you want to track and pull on demand. Build a list once (in the Specter app or via the API), then read its members' full, current records through a single call, and maintain it programmatically.
## What you can do
* Create and name a list, add or remove members, and delete it.
* Pull the full current records for everything on a list in one call.
* Keep lists in sync with your own systems (CRM, warehouse) without touching the app.
## Sharing a list with the API
A list is reachable from the API when it is created by the API, explicitly shared to the API (the "Share to API" toggle on the list in the app), or a global list curated by Specter. A list shared only within your team is not reachable, and lists that aren't shared won't appear in the API.
## Endpoints
Each list type (companies, people, investors) exposes the same six operations.
### Company lists
| Method | Endpoint | Returns |
| -------- | --------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `GET` | [Get all company lists](/api-reference/company-lists/get-all-company-lists) | Your company lists, their sizes, and their sharing fields |
| `POST` | [Create company list](/api-reference/company-lists/create-company-list) | The new list |
| `GET` | [Get company list](/api-reference/company-lists/get-company-list) | A list's metadata, sharing fields, and member company IDs |
| `PATCH` | [Update company list](/api-reference/company-lists/update-company-list) | The updated list |
| `DELETE` | [Delete company list](/api-reference/company-lists/delete-company-list) | Removes the list (irreversible) |
| `GET` | [Get company list results](/api-reference/company-lists/get-company-list-results) | The full current records for the list's companies |
### People lists
| Method | Endpoint | Returns |
| -------- | ------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `GET` | [Get all people lists](/api-reference/people-lists/get-all-people-lists) | Your people lists, their sizes, and their sharing fields |
| `POST` | [Create people list](/api-reference/people-lists/create-people-list) | The new list |
| `GET` | [Get people list](/api-reference/people-lists/get-people-list) | A list's metadata, sharing fields, and member person IDs |
| `PATCH` | [Update people list](/api-reference/people-lists/update-people-list) | The updated list |
| `DELETE` | [Delete people list](/api-reference/people-lists/delete-people-list) | Removes the list (irreversible) |
| `GET` | [Get people list results](/api-reference/people-lists/get-people-list-results) | The full current records for the list's people |
### Investor lists
| Method | Endpoint | Returns |
| -------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| `GET` | [Get all investor lists](/api-reference/investor-lists/get-all-investor-lists) | Your investor lists, their sizes, and their sharing fields |
| `POST` | [Create investor list](/api-reference/investor-lists/create-investor-list) | The new list |
| `GET` | [Get investor list](/api-reference/investor-lists/get-investor-list) | A list's metadata, sharing fields, and member investor IDs |
| `PATCH` | [Update investor list](/api-reference/investor-lists/update-investor-list) | The updated list |
| `DELETE` | [Delete investor list](/api-reference/investor-lists/delete-investor-list) | Removes the list (irreversible) |
| `GET` | [Get investor list results](/api-reference/investor-lists/get-investor-list-results) | The full current records for the list's investors |
## How to use the API
Get started analysing a set of companies:
1. **Create or pick a list.** Build it in the app, or create one with [Create company list](/api-reference/company-lists/create-company-list). List names must be unique.
2. **Make sure it's shared.** Created via the API, or "Share to API" on in the app.
3. **Find it.** [Get all company lists](/api-reference/company-lists/get-all-company-lists) to get its `listId` and size.
4. **Pull the records.** [Get company list results](/api-reference/company-lists/get-company-list-results) returns the full current profile for every company on the list, paginated.
5. **Maintain it.** [Update company list](/api-reference/company-lists/update-company-list) to add or remove members; [Delete company list](/api-reference/company-lists/delete-company-list) when done.
**Chain into the rest of the API.** List results (and the "list info" member IDs) give you company, person, or investor IDs; follow them to [Get company by ID](/api-reference/companies/get-company-by-id), [Get person by ID](/api-reference/people/get-person-by-id), or [Get investor by ID](/api-reference/investors/get-investor-by-id) for deeper detail.
## Good to know
* A list must be created by the API, explicitly shared to the API via "Share to API", or a global list curated by Specter to be reachable. Lists shared only within your team are not accessible from the API.
* List names must be unique (this rule applies to lists, not saved searches).
* Results are paginated; the record shape matches the underlying product object (company / person / investor).
* Both the collection and the per-list response carry `is_global`, which is `true` for lists curated by Specter, and `shared_with`, the Specter user IDs the list is shared with (`[]` when it is not shared). Resolve an ID to a person with [Get organization members](/api-reference/account/get-organization-members).
* Deleting a list is irreversible.
# LLMs.txt
Source: https://api.tryspecter.com/api-ref/llms
Machine-readable documentation for LLMs and AI agents.
Specter's documentation is published in formats designed for large language
models and AI agents, so tools can read the API reference directly.
* [llms.txt](https://api.tryspecter.com/llms.txt). A structured index of every
page in this documentation, with links and short summaries. Point an LLM or
agent here first to discover what's available.
* [llms-full.txt](https://api.tryspecter.com/llms-full.txt). The full text of
the documentation in a single file, for tools that want everything in one
request.
These files are generated automatically and stay in sync with the docs.
View any page as Markdown by appending `.md` to the URL (e.g.
`/introduction.md`). You can also copy or export pages, or send them directly to
tools like ChatGPT, Claude, or Perplexity from the page menu.
# Pagination
Source: https://api.tryspecter.com/api-ref/pagination
Page through large result sets with two query parameters: page and limit.
List endpoints support pagination using `page` and `limit`.
## Parameters
* `page`. Page index (starts at `0`)
* `limit`. Number of results per page (default: `50`)
## Example
```bash theme={null}
curl --request GET \
--url 'https://app.tryspecter.com/api/v1/searches/companies/5432/results?page=1&limit=500' \
--header 'X-API-Key: YOUR_API_KEY'
```
## Limits
* `limit` sets the page size, and its maximum depends on the endpoint family: by-date signal and transaction feeds and most per-entity endpoints cap `limit` at 50 per page, while list results and saved-search results endpoints accept up to 5000 per page. Some endpoints also cap the total rows available across pages (for example, company transaction histories return up to 1,000 rows). Each endpoint page states its own limits.
* Some endpoints use lower caps (e.g. name search: 10, people: 100, transactions: 1000)
* Exceeding the limit returns `400`
See each endpoint for its exact cap.
## When to stop
* If response headers include totals (`X-Total-Count`, `X-Total-Pages`), use them
* Where present, follow the RFC 5988 `Link` header (`next` / `prev` URLs) to walk pages
* Otherwise, stop when a page returns fewer than `limit` results
# Plans & Pricing
Source: https://api.tryspecter.com/api-ref/plans
Programmatic access to Specter's private-markets data and signals, metered in credits and requiring at least one paid web-app seat.
Specter's API gives programmatic access to its private-markets intelligence platform: structured data and proprietary signals on companies, people, investors, transactions, and your team's network. Usage is metered in credits; see [Rate Limits & Credit Limits](/api-ref/rate_limits) for how credits are charged, and each endpoint's page for its exact cost.
The API requires at least one paid seat. A few things can only be done in the web app and need that seat: retrieving your API key, managing your subscription, enabling extra usage, and creating saved searches and lists.
## What you get
* Core data on companies, people, investors, and transactions, each with a stable ID linked across the system.
* Signals for monitoring change and intent: talent moves, investor interest, revenue momentum, and news.
* Network mapping across your team's LinkedIn connections.
* Workflows to find and pull records in bulk: enrichment, lists, saved searches, and AI search in plain English.
* Account endpoints for team roster, usage, and credit balance.
## Trial
New to the API? Request 200 free credits in the [API console](https://app.tryspecter.com/settings/api-console) to get started, no commitment needed.
## Pricing
Plans scale from starter to enterprise depending on usage. [Talk to us](mailto:api-support@tryspecter.com) for details.
# Companies
Source: https://api.tryspecter.com/api-ref/products/companies
Firmographics, funding, headcount, traction and signals for millions of companies
Firmographics, funding, team intelligence, and real-time signals across 55M+ companies. Specter's companies dataset provides a continuously updated profile of each company, from early-stage startups to public enterprises. Each company has a stable `company_id` used across every endpoint.
## Data categories
* **Profile.** Name, description, tagline, HQ, founding year, operating status.
* **Classification.** Industry, tech verticals, business model, customer focus.
* **Team & headcount.** Employee count, department and location breakdowns, founders (`founder_info` with `specter_person_id`).
* **Funding & financials.** Funding history, investors, rounds, post-money valuation.
* **Transactions.** Acquisitions and IPOs.
* **Traction & signals.** Web traffic, engagement metrics, growth highlights, plus news, revenue, and investor-interest signals from the company's signal endpoints.
* **Social & reviews.** Social presence and product reviews (G2, Trustpilot, Glassdoor, Chrome).
* **News & external data.** Press mentions, awards, patents and trademarks.
## Highlights
The `highlights` (and `new_highlights`) array surfaces notable, AI-generated flags on a company. Documented values include:
* `headcount_surge`. Rapid team growth.
* `strong_web_traffic_growth`. Increasing web traction.
* `strong_social_growth`. Rising social engagement.
* `top_tier_investors`. Backed by leading funds.
* `no_recent_funding`. May be due a new round.
The list is being expanded, so treat it as non-exhaustive. Pair highlights with search filters to build target lists.
## Endpoints
| Method | Endpoint | Returns |
| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `POST` | [Find company ID](/api-reference/companies/find-company-id) | The Specter `company_id` for a domain, website, LinkedIn, Crunchbase or Pitchbook URL, or name (batch, free) |
| `GET` | [Search entities by name](/api-reference/search/search-entities-by-name) | Fuzzy name matches across companies, people, and investors (free) |
| `GET` | [Get company by ID](/api-reference/companies/get-company-by-id) | A full company profile by ID |
| `POST` | [Enrich companies (bulk)](/api-reference/enrich/enrich-companies-bulk) | Enrich up to 50 companies in one request |
| `POST` | [Get company competitors](/api-reference/companies/get-company-competitors) | A company's competitive landscape: ranked competitors and how the market splits |
| `GET` | [Get company employees](/api-reference/companies/get-company-employees) | Team and founders |
| `GET` | [Get company funding rounds](/api-reference/companies/get-company-funding-rounds) | Funding history |
| `GET` | [Get company acquisitions](/api-reference/companies/get-company-acquisitions) | Acquisitions the company made |
| `GET` | [Get company IPOs](/api-reference/companies/get-company-ipos) | IPO history |
| `GET` | [Get company latest revenue](/api-reference/companies/get-company-latest-revenue) | Latest revenue figures |
| `GET` | [Get company latest valuation](/api-reference/companies/get-company-latest-valuation) | Latest valuation figures |
| `GET` | [Get company news](/api-reference/companies/get-company-news) | News signals for the company |
| `GET` | [Get company revenue signals](/api-reference/companies/get-company-revenue-signals) | Revenue and profitability signals for the company |
| `GET` | [Get company investor-interest signals](/api-reference/companies/get-company-investor-interest-signals) | Investor attention on the company |
## How to use the API
**Start with what you have**
* A domain, website, LinkedIn URL, Crunchbase URL, Pitchbook URL, or name → [Find company ID](/api-reference/companies/find-company-id) → take the `company_id` (free, up to 50 at once).
* Want the full record for a domain or URL, and to source it if Specter doesn't have it → [Enrich company](/api-reference/enrich/enrich-company).
* A company ID already → [Get company by ID](/api-reference/companies/get-company-by-id).
**Expand from a company**
* Team and founders → [Get company employees](/api-reference/companies/get-company-employees). Each row carries the person's identity, socials, location, highlights and signal IDs; follow `person_id` to [Get person by ID](/api-reference/people/get-person-by-id) for experience, education and skills.
* Funding history → [Get company funding rounds](/api-reference/companies/get-company-funding-rounds). Each round carries `investor_id` and `is_lead_investor`, chainable to the Investors API.
* Acquisitions → [Get company acquisitions](/api-reference/companies/get-company-acquisitions). Double-sided, with both the acquirer and acquiree company IDs.
* Similar companies and the competitive landscape → [Get company competitors](/api-reference/companies/get-company-competitors). Ranked competitors and the dimensions the market splits on. It takes one company per call, so loop over your seeds.
* Real-time signals → [Get company latest revenue](/api-reference/companies/get-company-latest-revenue), [Get company latest valuation](/api-reference/companies/get-company-latest-valuation), [Get company news](/api-reference/companies/get-company-news), [Get company revenue signals](/api-reference/companies/get-company-revenue-signals), and [Get company investor-interest signals](/api-reference/companies/get-company-investor-interest-signals).
Note: the company profile's embedded investors and acquirer are names only; the chainable IDs live on the sub-resource endpoints (funding rounds, acquisitions).
## Notes
* [Find company ID](/api-reference/companies/find-company-id) is free and resolves up to 50 identifiers per request; exact identifiers (domain, website, LinkedIn URL, Crunchbase URL, Pitchbook URL) return one match, while a name returns up to 10 ranked candidates. It's the batch, no-cost way to get a `company_id`. [Search entities by name](/api-reference/search/search-entities-by-name) is the free single-query name search when you don't know whether the name belongs to a company, a person, or an investor; use Find company ID when you need to resolve exact identifiers.
* Most fields are nullable; only core identity (`company_id`, `organization_name`) is guaranteed.
* Enrichment may return more than one company when domains alias to each other.
* `404` = company not found. For the acquisitions and IPOs endpoints, `200` with an empty array `[]` means the company exists but has no such records.
* Sub-resource endpoints return the IDs you chain on across companies, people, and investors.
* [Get company competitors](/api-reference/companies/get-company-competitors) is a `POST` with an optional body: `limit` (1–30, default 30). It's cache-first and freshness is automatic: results older than 30 days are recomputed on the next call (`last_updated` shows when). `refresh` is no longer accepted, and sending it returns `422`. Each competitor carries a `competitiveness_score` (0–1) and, when the rival is in Specter's data set, a `company_id` you can chain to [Get company by ID](/api-reference/companies/get-company-by-id).
# Interest Signals
Source: https://api.tryspecter.com/api-ref/products/interest-signals
Detected investor attention: which investors are looking at which companies and founders, and how strongly.
Detect investor attention before deals are announced. Interest Signals show which investors are engaging with companies or founders, often weeks before a funding round or acquisition becomes public. Each signal captures who is interested, how strong the interest is, and what they're looking at.
## Data categories
* **Investor activity.** Which investors are showing interest (`signal_investors`, returned as names).
* **Signal strength.** A confidence score (`signal_score`, 1–10) based on engagement patterns.
* **Target.** The company or person the interest is focused on (`signal_type` is Company or Talent).
* **Context.** A plain-English `signal_summary`, plus funding context at signal time (`signal_total_funding_usd`, `signal_last_funding_date`) and `signal_date`.
* **Source type.** Where the signal was observed (`source_types`: insider, venture\_capital, angel, journalist, influencer, investment\_bank, private\_equity, investor).
```json Example (trimmed) theme={null}
{
"signal_id": "02d32673-f1ab-40a1-93c5-a3a36a10d342",
"signal_date": "2025-12-01",
"signal_type": "Company",
"signal_score": 9,
"signal_summary": "Porcupine VC are in talks with Hedgehog Analytics as it seeks seed capital.",
"source_types": "insider",
"entity_id": "5e3a7f2b0aa7a3270a55f2a8",
"signal_investors": [{ "name": "Bluebirds Capital" }]
}
```
## Endpoints
| Method | Endpoint | Returns |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `GET` | [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date) | The signal feed: the whole dataset, or scoped to a saved search or a list |
| `GET` | [Get company investor-interest signals](/api-reference/companies/get-company-investor-interest-signals) | Interest shown in one company |
| `GET` | [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals) | Interest shown by one investor |
| `GET` | [Get investor-interest saved search](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search) | A saved search's name, query ID, and count |
| `GET` | [Get investor-interest saved search results](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search-results) | Signals matching a saved search |
## How to use the API
**Monitor a feed (most common)**
Create an Interest Signals search in the Specter app and share it with the API, then poll [Get investor-interest saved search results](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search-results) with `new_results_after` set to your last read, to pull only the signals added since. Discover the `searchId` with [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
[Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date) covers the same ground without a saved search, and can be scoped three ways: `search_id` for a saved search, `list_id` for the members of a list, or neither for the whole dataset. `signal_date_after` / `signal_date_before` bound the window in every mode.
**Focus on one entity**
* A company → [Get company investor-interest signals](/api-reference/companies/get-company-investor-interest-signals). Every signal attributed to that company, newest first.
* An investor → [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals). Everything that investor has shown interest in.
* A person → there's no per-person endpoint; sweep [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date) and keep the Talent-type signals whose `entity_id` is the `person_id` you're after.
Both entity-scoped endpoints take one ID per call, so loop over your cohort; each accepts the same date bounds.
**Expand from a signal**
* `entity_id` → [Get company by ID](/api-reference/companies/get-company-by-id) (Company signals) or [Get person by ID](/api-reference/people/get-person-by-id) (Talent signals). When `entity_id` is absent, use the embedded company domain or person `linkedin_url`.
* `signal_investors[].name` → resolve to a Specter record via [Enrich investor](/api-reference/enrich/enrich-investor) or [Search entities by name](/api-reference/search/search-entities-by-name) (the signal carries investor names, not IDs).
## Good to know
* Signals use UUIDs.
* `signal_score` is a 1–10 confidence score.
* `signal_type` is Company or Talent; the target can be a company or a person.
* `entity_id` is the company ID (Company signals) or person ID (Talent signals); it may be absent, in which case use the embedded company domain or person `linkedin_url`.
* Investors are returned as names (`signal_investors[].name`), not IDs; resolve them via investor lookup.
* Saved searches must be shared with the API to be reachable; empty results are valid, not an error.
* Every endpoint here is charged per signal returned, so bound the date range before widening pages. The entity-scoped endpoints page at 50 results; see each endpoint's "Costs" note.
* On the entity-scoped endpoints an unknown company or investor returns `404`, while a known one with no signals returns `200` with an empty array.
# Investors
Source: https://api.tryspecter.com/api-ref/products/investors
Investor records for VC, PEs, Funds, Angels, etc.: targeting, activity, funds raised and portfolios and linked to the companies and rounds they touch.
Profiles, fund activity, and investment signals across 330K+ investors. Specter's investor dataset covers venture firms, private equity, angels, and institutional investors. Each investor has a stable `investor_id` (prefixed `inv_`) used across every endpoint.
## Data categories
* **Profile.** Name, description, HQ, founding year, organisation size, social profiles.
* **Classification.** Investor types (e.g. `venture_capital`, `angel_group`), investment stage, and industry / tech-vertical targeting.
* **Fund details.** Named funds with announce date and amount raised (`fund_details`).
* **Portfolio.** Backed companies as Specter company IDs (`portfolio_companies`).
* **Activity.** `number_of_investments`, `number_of_lead_investments`, `number_of_exits`, `number_of_funds`.
* **Signals.** Investor-interest signals, from [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals).
* **Linkages.** `person_id` (when the investor is an individual, e.g. an angel) and `company_id` (the firm's company record); either, both, or neither may be null.
## Targeting & activity
What to screen investors on, all real fields on the record:
* **Stage focus.** `investment_stage` (Seed through Growth).
* **Sector focus.** `industry_target`, `specter_industry_target`, `specter_tech_verticals_target`.
* **Deal activity.** `number_of_investments`, `number_of_lead_investments`, `number_of_exits`.
* **Fund scale.** `number_of_funds` and `fund_details` (amounts raised).
```json Example (trimmed) theme={null}
{
"investor_id": "inv_609dba55408c4490fe58cf8e",
"investor_name": "Bessemer Venture Partners",
"investor_types": ["venture_capital"],
"investment_stage": ["Series A", "Series B"],
"number_of_investments": 1581,
"number_of_exits": 325,
"fund_details": [
{ "name": "BVP Fund XII", "announced_on": "2023-04-12", "raised_amount_usd": 3850000000 }
],
"portfolio_companies": ["5e3bbf6b00c8f4c966a1e53d"],
"strategic_signal_ids": ["ddea4a84-ffdc-459d-bb10-3d7db9c6c193"]
}
```
## Endpoints
| Method | Endpoint | Returns |
| ------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `POST` | [Find investor ID](/api-reference/investors/find-investor-id) | The Specter `investor_id` for a website or name (batch, free) |
| `GET` | [Search entities by name](/api-reference/search/search-entities-by-name) | Fuzzy name matches across companies, people, and investors (free) |
| `GET` | [Get investor by ID](/api-reference/investors/get-investor-by-id) | A full investor profile by ID |
| `POST` | [Enrich investors (bulk)](/api-reference/enrich/enrich-investors-bulk) | Enrich up to 50 investors in one request |
| `GET` | [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds) | An investor's investment history |
| `GET` | [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals) | The interest this investor has shown in companies and talent |
## How to use the API
**Start with what you have**
* Name or domain → [Find investor ID](/api-reference/investors/find-investor-id) → take the `investor_id` (free, up to 50 at once), or [Enrich investor](/api-reference/enrich/enrich-investor) for the full record in one step.
* Partial name → [Search entities by name](/api-reference/search/search-entities-by-name) → take the `id` of a match in the `investors` group (free; it's the `investor_id`).
* Investor ID → [Get investor by ID](/api-reference/investors/get-investor-by-id).
**Expand from an investor**
* Portfolio → follow each ID in `portfolio_companies` to [Get company by ID](/api-reference/companies/get-company-by-id).
* Deals → [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds).
* Interest signals → [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals). Every signal attributed to the investor, newest first, bounded with `signal_date_after` / `signal_date_before`.
* Angel or firm → when `person_id` is set, [Get person by ID](/api-reference/people/get-person-by-id); when `company_id` is set, [Get company by ID](/api-reference/companies/get-company-by-id) for the firm's company record.
## Notes
* Lookups may return more than one investor when several share a domain.
* Bulk lookups return matched results only; unknown identifiers are omitted.
* [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals) paginates at 50 per page and is charged per signal returned; an investor with no active interest signals returns `200` with an empty array, an unknown one `404`.
* Funding rounds are paginated, newest first. Use returned IDs to traverse across companies, people, and deals.
# Network Mapping
Source: https://api.tryspecter.com/api-ref/products/network
Your team's LinkedIn connections as a queryable graph: find a warm path into a target company, or see who already knows a given contact.
Your team's LinkedIn connections as a queryable graph: find a warm path into a target company, or see who already knows a given contact. Connections are deduplicated across all your teammates.
## Data categories
* **Identity.** `person_id` (prefixed `per_`), `full_name`, `headline`, `linkedin_url`, `primary_role`.
* **The connection.** `connected_on` (`linkedin`), `connected_at`, `connected_teammates` (Specter `user_` IDs of the teammates who hold it).
* **Current employer.** `current_company_id`.
```json Example (trimmed) theme={null}
{
"person_id": "per_5f3a2b1c4d5e6f7a8b9c0d1e",
"full_name": "Jane Doe",
"headline": "Engineering Lead @ Acme · ex-Google",
"current_company_id": "66d926166261234567890123",
"connected_on": "linkedin",
"connected_teammates": ["user_2opva2jahltnNL8xOK7vArM0IBg"]
}
```
## Endpoints
| Method | Endpoint | Returns |
| ------ | --------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `GET` | [Get network people](/api-reference/network/get-network-people) | Everyone your team is connected to |
| `GET` | [Get network companies](/api-reference/network/get-network-companies) | Companies where your contacts work |
| `GET` | [Get network connections at a company](/api-reference/network/get-network-connections-at-a-company) | Your connections at a specific company |
## How to use the API
**Start with what you have**
* Browsing your whole network → [Get network people](/api-reference/network/get-network-people) or [Get network companies](/api-reference/network/get-network-companies).
* A target company → [Get network connections at a company](/api-reference/network/get-network-connections-at-a-company).
* A teammate `user_id` from a result → [Get organization members](/api-reference/account/get-organization-members).
**Expand from a result**
* `person_id` → [Get person by ID](/api-reference/people/get-person-by-id).
* `current_company_id` → [Get company by ID](/api-reference/companies/get-company-by-id).
* `connected_teammates` → [Get organization members](/api-reference/account/get-organization-members) to put a name to each teammate.
## Notes
* The network reflects LinkedIn connections your teammates have synced, deduplicated across the team.
* `connected_on` only supports `linkedin` today.
* [Get network connections at a company](/api-reference/network/get-network-connections-at-a-company) returns `404` when you have no connections there.
* Use the `min_connections` filter on the companies endpoint to focus on companies where you have real depth.
* Network endpoints are paginated feeds, charged per request; see each endpoint's "Costs" note for the exact figure.
* Resolving a teammate `user_id` to a name uses [Get organization members](/api-reference/account/get-organization-members), which now lives in the Account section and is free.
# News Signals
Source: https://api.tryspecter.com/api-ref/products/news-signals
The articles Specter monitors, turned into structured, company-attributed events with an AI summary and an importance score.
Structured, company-attributed news from the articles Specter monitors. Each signal is one classified company mention within a single article (so an article naming three companies produces three signals), with an AI summary of what's newsworthy and a 0–5 importance score.
## Data categories
* **Article.** `article_id` (shared across signals from the same article), `article_url`, `title`, `published_date`, `featured_image_url`.
* **Classification.** `meaningful_updates`: `REVENUE_UPDATE`, `PROFIT_UPDATE`, `TRACTION_UPDATE`, `FUNDING_UPDATE`, `DEAL_UPDATE`.
* **Summary & importance.** `whats_new` (AI summary), `score` (0–5; 4+ is major news), `traction`.
* **Company link.** `entity_id`, `company_name`, `company_domain`.
```json Example (trimmed) theme={null}
{
"signal_id": 1234567,
"article_url": "https://techcrunch.com/2025/06/15/acme-series-b/",
"published_date": "2025-06-15",
"title": "Acme raises $40M Series B led by Lead VC",
"entity_id": "66d926166261234567890123",
"company_name": "Acme",
"meaningful_updates": ["FUNDING_UPDATE"],
"whats_new": "Acme raised a $40M Series B led by Lead VC.",
"score": 4
}
```
## Endpoints
| Method | Endpoint | Returns |
| ------ | ------------------------------------------------------------- | -------------------------------------- |
| `GET` | [Get company news](/api-reference/companies/get-company-news) | A company's news history, newest first |
## How to use the API
**Start from a company**
News is served per company by [Get company news](/api-reference/companies/get-company-news), which returns that company's complete news history from its Specter company ID. Only have a domain, website, or name? Resolve it first with [Find company ID](/api-reference/companies/find-company-id) (free, up to 50 at once) or [Search entities by name](/api-reference/search/search-entities-by-name).
**Cover a list or a saved search**
There is no list- or search-scoped news endpoint; fan out over the members instead.
* A list → pull its companies with [Get company list results](/api-reference/company-lists/get-company-list-results), then call [Get company news](/api-reference/companies/get-company-news) for each company `id`.
* A saved search → same shape, starting from [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results).
**Filter**
* Set `major_only=true` to restrict to signals scoring ≥ 4.
* Bound the window with `news_publication_date_after` / `news_publication_date_before` (both inclusive) — the cheapest way to poll a large cohort is a narrow date range per company.
**Expand from a signal**
* Company → follow `entity_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
* Article → every signal already carries the full article context (`article_url`, `title`, `whats_new`, `score`), so no follow-up lookup is needed.
## Notes
* One signal = one company mention in one article. Articles naming multiple companies share an `article_id`.
* `score` runs 0–5; 4+ is treated as major news (`major_only` filters to those).
* `meaningful_updates` classifies the news: revenue, profitability, traction, funding, or deals.
* `signal_id` is a plain integer (not a prefixed string).
* [Get company news](/api-reference/companies/get-company-news) is charged per block of results returned rather than per signal, so a full page costs the same as a nearly empty one; pull wide pages instead of many narrow ones. See its "Costs" note for the figure.
* An unknown company returns `404`; a known company with no coverage returns `200` with an empty array.
# People
Source: https://api.tryspecter.com/api-ref/products/people
Professional profiles including career history, education, skills and contact routes, for the people behind the companies.
Professional profiles with career history, education, and real-time signals. Specter's people dataset covers 550M+ profiles: founders, executives, investors, and operators. Each person has a stable `person_id` used across every people endpoint.
## Data categories
* **Profile.** Name, tagline, about, location, profile picture, LinkedIn follower and connection counts.
* **Career history.** `experience[]`: companies, titles, tenure, and progression (`is_current`, `job_order`).
* **Education.** `education[]`: institutions, degrees, and fields of study.
* **Skills & attributes.** Skills, languages, seniority, years of experience, education level.
* **Signals.** Talent signals for the person, from [Get person talent signals](/api-reference/people/get-person-talent-signals).
* **Social links.** LinkedIn, Twitter and GitHub URLs, plus `linkedin_num_id` and `linkedin_urn`.
Looking for a person's team-network connections? See [Network](/api-ref/products/network). For investor profiles, funds, and activity, see [Investors](/api-ref/products/investors).
## Highlights
The `highlights` array flags high-signal attributes for evaluating a person, especially founders. Documented values include:
* `prior_exit`. Founded or was part of a company with a successful exit.
* `serial_founder`. Founded more than one company.
* `prior_vc_backed_founder`. Previously founded a venture-backed company.
* `prior_vc_backed_experience`. Worked at a venture-backed company.
This list is being expanded, so treat it as non-exhaustive. Pair highlights with company filters to spot strong founding teams.
```json Example (trimmed) theme={null}
{
"person_id": "per_7f8d9e2a1b3c4d5e6f7g8h9i0",
"full_name": "Sarah Chen",
"tagline": "AI Researcher | Ex-Google | Founder of VisionAI (Acquired by NVIDIA)",
"location": "San Francisco, California, United States",
"current_position_title": "Senior Research Scientist",
"current_position_company_name": "Google AI",
"highlights": ["prior_exit", "serial_founder"],
"talent_signal_ids": ["02d32673-f1ab-40a1-93c5-a3a36a10d342"],
"linkedin_url": "https://www.linkedin.com/in/sarahchen9776"
}
```
## Endpoints
| Method | Endpoint | Returns |
| ------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `POST` | [Find person ID](/api-reference/people/find-person-id) | The Specter `person_id` for a LinkedIn URL, vanity id, numeric id, or URN (batch, free) |
| `GET` | [Search entities by name](/api-reference/search/search-entities-by-name) | Fuzzy name matches across companies, people, and investors (free) |
| `GET` | [Get person by ID](/api-reference/people/get-person-by-id) | A full person profile by ID |
| `POST` | [Enrich people (bulk)](/api-reference/enrich/enrich-people-bulk) | Enrich up to 50 people in one request |
| `GET` | [Get person email](/api-reference/people/get-person-email) | A person's verified email |
| `GET` | [Get person talent signals](/api-reference/people/get-person-talent-signals) | A person's talent-signal history |
## How to use the API
**Start with what you have**
* LinkedIn URL or identifier → [Find person ID](/api-reference/people/find-person-id) → take the `person_id` (free, up to 50 at once), or [Enrich person](/api-reference/enrich/enrich-person) when you want the profile fetched for someone Specter may not hold yet.
* Email → [Enrich person by email](/api-reference/enrich/enrich-person-by-email).
* Name → [Search entities by name](/api-reference/search/search-entities-by-name) → take the `id` of a match in the `people` group (free; it's the `person_id`).
**Expand from a person**
* Full profile → [Get person by ID](/api-reference/people/get-person-by-id).
* Verified email → [Get person email](/api-reference/people/get-person-email).
* Talent signals → [Get person talent signals](/api-reference/people/get-person-talent-signals). The person's whole signal history, newest first, each entry carrying the signal detail and the embedded profile. Bound it with `signal_date_after` / `signal_date_before`.
* Investor interest in the person → interest signals are served as a feed, not per person: [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date), where Talent-type signals carry the `person_id` in `entity_id`.
* Current employer → take `company_id` from the current `experience[]` entry (`is_current: true`) → [Get company by ID](/api-reference/companies/get-company-by-id) (the profile carries the current company's name, not a top-level ID).
## Notes
* Most fields are nullable; only core identity (`person_id`, name, LinkedIn URL) is guaranteed.
* The by-email endpoints return the full person record, the same object as [Get person by ID](/api-reference/people/get-person-by-id), plus the resolved email and a `score` from 1–10; 7 or higher is a reliable match. Roles live in `experience[]`, each with its own `company_id`; there is no top-level `company_id`. No match returns `204`.
* Bulk lookups omit unknown identifiers; bulk enrich returns a found/queued status per row, and only found rows are charged.
* [Get person talent signals](/api-reference/people/get-person-talent-signals) paginates at 50 per page and is charged per signal returned; a known person with no signals returns `200` with an empty array, an unknown one `404`.
* Enriching an unknown person queues them for sourcing; retry the lookup shortly after.
# Revenue Signals
Source: https://api.tryspecter.com/api-ref/products/revenue-signals
Revenue and profitability data points for companies, extracted from news coverage and public filings; each with its figure, year, source, and company.
Revenue and profitability signals from news, filings, and public disclosures. Revenue Signals capture structured financial data points for companies (revenue, ARR, and profitability), each with a source, time period, and company attribution. Each signal is a single observation tied to a company and a point in time.
## Data categories
* **Revenue metrics.** `metric` (ARR, Revenue, or GMV), `annualized_usd`, `year`.
* **Profitability.** `is_profitable`, `profitability_annual_usd`, `profitability_year` (when available).
* **Timing.** `reference_date` (the period the figure refers to) and `signal_date` (when it was observed).
* **Source.** `source_type` (news, social, or public), `source_url`.
* **Context.** `tags` (e.g. `PROJECTION`, `public`), `whats_new`, `context`.
* **Company link.** `entity_id` (company ID) and `company_name`.
```json Example (trimmed) theme={null}
{
"signal_id": "rev_e3b0c44298fc1c149afbf4c8996fb924",
"signal_date": "2025-06-15",
"entity_id": "66d926166261234567890123",
"company_name": "Acme Corp",
"metric": "ARR",
"annualized_usd": 40000000,
"year": 2025,
"is_profitable": true,
"tags": ["PROJECTION"],
"source_url": "https://www.example.com/articles/acme-q2-update"
}
```
## Endpoints
| Method | Endpoint | Returns |
| ------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `GET` | [Get company revenue signals](/api-reference/companies/get-company-revenue-signals) | A single company's full revenue-signal history (by Specter company ID), newest first |
| `GET` | [Get revenue signals by date](/api-reference/revenue-signals/get-revenue-signals-by-date) | Revenue signals across all companies in a date range, newest first |
## How to use the API
**Start with what you have**
* A Specter company ID → [Get company revenue signals](/api-reference/companies/get-company-revenue-signals). Only have a domain or name? [Find company ID](/api-reference/companies/find-company-id) first, then call this with the returned `company_id`.
* No particular company, or a wide sweep → [Get revenue signals by date](/api-reference/revenue-signals/get-revenue-signals-by-date), bounded with `revenue_signal_date_after` / `revenue_signal_date_before`.
**Cover a list or a saved search**
There is no list- or search-scoped revenue endpoint; fan out over the members instead.
* A list → pull its companies with [Get company list results](/api-reference/company-lists/get-company-list-results), then call [Get company revenue signals](/api-reference/companies/get-company-revenue-signals) for each company `id`.
* A saved search → same shape, starting from [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results).
Because revenue signals are billed per signal returned, keep the date range tight when fanning out over a large cohort.
**Track updates**
* Poll with `revenue_signal_date_after` set to the end of your last read to pick up only what has been published since.
**Expand from a signal**
* Company → follow `entity_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
* Full detail → already included: both endpoints return the complete signal object, with `source_url`, `context`, and the profitability fields.
## Notes
* Signal IDs are prefixed `rev_`.
* `entity_id` may be null when the company is referenced upstream but isn't in Specter's company DB.
* `tags` qualify the figure: `PROJECTION` means a forecast, `public` means a public-filing figure.
* Financial fields are null when not disclosed.
* Revenue signals are premium data: both endpoints are charged per signal returned and cost more than other signals. See each endpoint's "Costs" note for exact figures.
* The date bounds are inclusive, and `limit`/`page` paginate. An unknown company returns `404`; a known company with no signals returns `200` with an empty array.
# Talent Signals
Source: https://api.tryspecter.com/api-ref/products/talent-signals
Detected career moves (founders going into stealth, executives changing roles), often months before they're announced.
Track high-signal career moves before they're public. Talent Signals surface the people moves that matter in private markets (new founders, stealth startups, and key hires), often before a company is announced, before a round is disclosed, or before a hire shows up in a press release. Each signal pairs the event with the full profile of the person it's about, so you can act on it immediately.
## Data categories
* **New founders.** People leaving roles to start companies, including stealth activity.
* **Job changes.** Senior hires, promotions, and role switches across companies.
* **Stealth activity.** Early signals of companies being built before public launch.
* **Career context.** Previous roles, companies, and background to judge signal quality (the full profile is embedded in every signal).
* **Signal quality.** A confidence score (`signal_score`, 1–10) and timing indicators (`out_of_stealth_advantage`, months caught before the public announcement).
```json Example (trimmed) theme={null}
{
"talent_signal_id": "02d32673-f1ab-40a1-93c5-a3a36a10d342",
"person_id": "per_7f8d9e2a1b3c4d5e6f7g8h9i0",
"full_name": "Sarah Chen",
"signal_type": "New Company",
"signal_status": "Stealth",
"signal_score": 9,
"out_of_stealth_advantage": 6,
"new_position_title": "Founder & CEO",
"new_position_company_id": "5e3a7f2b0aa7a3270a55f2b9",
"new_position_company_name": "VisionAI",
"past_position_company_id": "5e3a7f2b0aa7a3270a55f2a8",
"signal_summary": "Sarah has co-founded VisionAI, a computer-vision platform for enterprise.",
"highlights": ["prior_exit", "serial_founder"]
}
```
## Endpoints
| Method | Endpoint | Returns |
| ------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `GET` | [Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date) | Every signal in a date range, across all people, newest first |
| `GET` | [Get person talent signals](/api-reference/people/get-person-talent-signals) | One person's complete signal history |
| `GET` | [Get talent signal saved search](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search) | A saved search's name, query ID, and match count |
| `GET` | [Get talent signal saved search results](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search-results) | Signals matching a saved search |
## How to use the API
**Monitor a feed (most common)**
Create a Talent Signals search in the Specter app and share it with the API, then poll [Get talent signal saved search results](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search-results) with `new_results_after` set to your last read, to pull only the signals added since. Discover the `searchId` with [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
**Sweep a date range**
[Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date) returns every signal across all people, newest first. Bound it with `signal_date_after` / `signal_date_before` (both inclusive) and page through with `page`/`limit` (50 per page). Use it to backfill history or to catch everything in a window without a saved search.
**Look up one person's signals**
[Get person talent signals](/api-reference/people/get-person-talent-signals) returns a single person's complete signal history from their `person_id`, newest first, with the same date bounds. Don't have the ID? [Search entities by name](/api-reference/search/search-entities-by-name) resolves it for free. Signals are fetched one person at a time, so loop over your cohort.
**Expand from a signal**
* `person_id` → [Get person email](/api-reference/people/get-person-email) or [Get person by ID](/api-reference/people/get-person-by-id) (the profile is already embedded; use these for the email or a refresh).
* `new_position_company_id` → [Get company by ID](/api-reference/companies/get-company-by-id) (the new company).
* `past_position_company_id` → [Get company by ID](/api-reference/companies/get-company-by-id) (the previous company).
## Good to know
* Talent signal IDs are UUIDs; the `person_id` is prefixed `per_`.
* `signal_score` is a 1–10 confidence score; `out_of_stealth_advantage` is how many months early Specter caught the move versus the public announcement.
* Every signal embeds the full person profile (career history, education, skills, and links), so no extra call is needed for the profile itself.
* `talent_last_signal` is true when it's the person's most recent signal.
* Saved searches must be shared with the API (or created via it) to be reachable; empty results are valid, not an error.
* Every endpoint here is charged per signal returned. [Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date) and [Get person talent signals](/api-reference/people/get-person-talent-signals) page at 50 results, so a full page costs 50 credits; narrow the date range before widening the page count. See each endpoint's "Costs" note.
# Transactions
Source: https://api.tryspecter.com/api-ref/products/transactions
Funding rounds, acquisitions and IPOs each with a stable ID and both sides of the deal resolvable
Funding rounds, acquisitions, and IPOs across 1M+ global transactions. Specter's transactions dataset captures deal activity across private and public markets. Each transaction has a stable ID (`fnr_`, `acq_`, `ipo_`) and links directly to the companies and investors involved.
## Data categories
* **Funding rounds.** `investment_type` (Seed through Series J, plus Undisclosed), `raised_amount_usd`, `announced_on`, pre- and post-money valuations, and the full `investors` list with an `is_lead_investor` flag.
* **Acquisitions.** Both sides of the deal (`acquirer_company_id` / `acquiree_company_id` with names and domains), `acquisition_type` (acquisition, merge, lbo, acquihire, management\_buyout), `price_usd`, `acquisition_date`.
* **IPOs.** Issuing company, exchange, ticker, pricing, and capital raised.
* **Participants.** Investors and companies, resolvable to full profiles via their IDs.
```json Example: funding round (trimmed) theme={null}
{
"funding_round_id": "fnr_1a2b3c4d5e6f",
"name": "Series A",
"company_id": "66d926166261234567890123",
"company_name": "Acme Inc.",
"investment_type": "Series A",
"announced_on": "2024-03-01",
"raised_amount_usd": 20000000,
"post_money_valuation_usd": 100000000,
"investors": [
{ "investor_id": "inv_1a2b3c4d5e6f", "investor_name": "Bessemer Venture Partners", "is_lead_investor": true }
]
}
```
## Endpoints
| Method | Endpoint | Returns |
| ------ | ------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `GET` | [Get funding rounds by date](/api-reference/transactions/get-funding-rounds-by-date) | Funding rounds across all companies in a date range |
| `GET` | [Get acquisitions by date](/api-reference/transactions/get-acquisitions-by-date) | Acquisitions across all companies in a date range |
| `GET` | [Get IPOs by date](/api-reference/transactions/get-ipos-by-date) | IPOs across all companies in a date range |
| `GET` | [Get company funding rounds](/api-reference/companies/get-company-funding-rounds) | A company's funding history |
| `GET` | [Get company acquisitions](/api-reference/companies/get-company-acquisitions) | A company's M\&A activity |
| `GET` | [Get company IPOs](/api-reference/companies/get-company-ipos) | A company's IPOs |
| `GET` | [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds) | Rounds an investor took part in |
| `GET` | [Get funding round by ID](/api-reference/transactions/get-funding-round-by-id) | A single funding round |
| `GET` | [Get acquisition by ID](/api-reference/transactions/get-acquisition-by-id) | A single acquisition |
| `GET` | [Get IPO by ID](/api-reference/transactions/get-ipo-by-id) | A single IPO |
## How to use the API
**Start with what you have**
* No particular company, or a market-wide sweep → [Get funding rounds by date](/api-reference/transactions/get-funding-rounds-by-date), [Get acquisitions by date](/api-reference/transactions/get-acquisitions-by-date) or [Get IPOs by date](/api-reference/transactions/get-ipos-by-date). These are the only endpoints that return transactions across all companies rather than for a single company or investor; bound them with the inclusive date parameters and page at 50.
* A company → [Get company funding rounds](/api-reference/companies/get-company-funding-rounds), [Get company acquisitions](/api-reference/companies/get-company-acquisitions), or [Get company IPOs](/api-reference/companies/get-company-ipos).
* An investor → [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds).
* A transaction ID → [Get funding round by ID](/api-reference/transactions/get-funding-round-by-id) (`fnr_`), [Get acquisition by ID](/api-reference/transactions/get-acquisition-by-id) (`acq_`), or [Get IPO by ID](/api-reference/transactions/get-ipo-by-id) (`ipo_`).
**Expand from a transaction**
* Funding round → each investor's `investor_id` → [Get investor by ID](/api-reference/investors/get-investor-by-id).
* Acquisition → `acquirer_company_id` or `acquiree_company_id` → [Get company by ID](/api-reference/companies/get-company-by-id).
* IPO → issuing company → [Get company by ID](/api-reference/companies/get-company-by-id).
## Notes
* Transaction data is usually reached via a company or an investor, then drilled into by transaction ID.
* Deal terms (amount, valuation) are null when undisclosed; never 0.
* Funding rounds carry the full investor list with a lead flag (`is_lead_investor`); acquisitions carry both the acquirer and acquiree company IDs.
* Transaction IDs are prefixed (`fnr_`, `acq_`, `ipo_`); the company and investor IDs inside them chain to the Companies and Investors APIs.
# Quickstart
Source: https://api.tryspecter.com/api-ref/quickstart
Get access, authenticate, and make your first request to the Specter API.
Get your API key and make your first request to the Specter API.
Your API key lives in the [API Console](https://app.tryspecter.com/settings/api-console). Open it and copy your key. No key yet? Click **Request API Access** there; requests are reviewed and approved within one business day. Send the key in the `X-API-Key` header on every request.
Resolve a domain to its Specter company ID. This call is free:
```bash theme={null}
curl --request POST \
--url https://app.tryspecter.com/api/v1/companies/resolve \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{ "to_resolve": [{ "domain": "hedgehog_analytics.com" }] }'
```
Response, one result group per identifier you sent:
```json theme={null}
[
{
"query": { "domain": "hedgehog_analytics.com" },
"matches": [
{
"id": "1a2b3c4d5e6g1a2b3c4d5e6g",
"name": "Hedgehog Analytics",
"domain": "hedgehog_analytics.com",
"hq": { "city": "London", "country": "United Kingdom" },
"founded_year": 2019,
"match_confidence": 1
}
]
}
]
```
If you receive a response, your API key is working.
Take `matches[0].id` from that response and retrieve the full company record:
```bash theme={null}
curl --request GET \
--url https://app.tryspecter.com/api/v1/companies/1a2b3c4d5e6g1a2b3c4d5e6g \
--header 'X-API-Key: YOUR_API_KEY'
```
Response:
```json theme={null}
{
"id": "1a2b3c4d5e6g1a2b3c4d5e6g",
"organization_name": "Hedgehog Analytics",
"website": {
"domain": "hedgehog_analytics.com",
"url": "https://www.hedgehog_analytics.com"
},
"hq": { "city": "London", "country": "United Kingdom" },
"employee_count": 39,
"funding": {
"total_funding_usd": 16600000,
"last_funding_type": "series_a"
},
"last_updated": "2026-01-01"
}
```
See [Rate Limits & Credit Limits](/api-ref/rate_limits) for your allowances and [Errors](/api-ref/errors) for what happens when you run out.
From here, you can expand into related data (team, investors, transactions) using the returned company `id`.
# Rate Limits & Credit Limits
Source: https://api.tryspecter.com/api-ref/rate_limits
Two meters govern every request: how fast you can call (rate) and how much data you can pull (credits).
Two meters govern every request: how fast you can call (rate) and how much data you can pull (credits). Each has its own headers and error code.
## Rate limits
Each API key allows **15 requests per second**. Exceed it and requests return `429 RATE_LIMITED`; wait for the one-second window to reset, then retry.
### Headers
| Header | Meaning |
| ----------------------- | ----------------------------------- |
| `X-RateLimit-Limit` | Max requests per second |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `X-RateLimit-Reset` | Seconds until reset |
### Notes
* Limits apply per API key, shared across your team; parallel jobs draw on the same budget.
* Bulk endpoints (up to 50 items per request) cut your request volume.
## Credit usage
Data is metered in credits per billing period. Every reference page states its exact cost in a note at the top.
### How credits are charged
Whether a call costs credits comes down to whether it manages configuration or retrieves data, and, for data, how much it returns. Every reference page states the exact figure in a "Costs ..." note at the top of its description; treat that as the source of truth.
**Free (no credits):**
* List management: get all, create, get, update, and delete lists.
* Saved-search management: get all, get, and delete a saved search.
* Account calls: [Get organization members](/api-reference/account/get-organization-members), [Get API call logs](/api-reference/account/get-api-call-logs), and Get credit balance.
* [Find company ID](/api-reference/companies/find-company-id).
* The unauthenticated health check.
**Charged (data retrieval):**
* Enrichment and by-ID lookups are charged per matched result, so a miss costs nothing.
* Paginated feeds are charged per request, per page.
* List results and saved-search results are charged per result returned.
* Premium data (such as verified email and revenue signals) costs more per result.
Creating or editing a list or saved search never costs credits; you pay only when you pull data. When credits run out, requests return `402 OUT_OF_CREDITS` and stop until the allowance resets.
### Headers
The `X-CreditLimit-*` headers appear on `402 OUT_OF_CREDITS` and `429` responses:
| Header | Meaning |
| ------------------------- | ---------------------------- |
| `X-CreditLimit-Limit` | Total credits for the period |
| `X-CreditLimit-Remaining` | Credits left |
| `X-CreditLimit-Reset` | Seconds until credits renew |
## Daily spending limit
Your monthly budget is one ceiling; a **daily limit** is a second, tighter one that you set yourself. A workspace admin turns it on under **Settings → API Console**, and from then on your organization's API calls stop for the rest of the day once the day's charges reach it. The count clears at **00:00 UTC**, so a bug that loops costs one day's limit rather than the month's budget.
No limit is set by default, and setting one is the only way it applies — nothing changes for an organization that hasn't.
The limit covers **API calls only**. Specter Agent runs and MCP tool calls draw on the same credit budget and are not subject to it, so they keep spending after the limit is reached and their usage is not counted in `daily_used`. Cap those in the Agent and MCP settings instead.
Once the limit is reached, requests return `402 DAILY_CREDIT_CAP_REACHED`. That is a different code from `OUT_OF_CREDITS` because the remedy is different: no top-up is needed, the limit simply clears at midnight UTC. Raising or removing it is an admin action in the API console — the API cannot change it, deliberately, so a runaway client can't lift its own ceiling.
Read where you stand with [`GET /organization/credits`](/api-reference/account/get-credit-balance), which reports `daily_cap`, `daily_used` and `daily_remaining` (`daily_cap` is `0` when no limit is set). The call is free and stays readable when the limit is reached.
### Headers
These accompany every response while a daily limit is set, and are the headers a `402 DAILY_CREDIT_CAP_REACHED` carries:
| Header | Meaning |
| ------------------------------- | ---------------------------------------------- |
| `X-CreditLimit-Daily-Limit` | Your organization's daily credit limit |
| `X-CreditLimit-Daily-Remaining` | Credits left before today's limit is reached |
| `X-CreditLimit-Daily-Reset` | Seconds until 00:00 UTC, when the limit clears |
## Best practices
* Track credit usage client-side (you know each call's cost up front) so a `402` never surprises you mid-run; `X-CreditLimit-Reset` tells you when it renews.
* Set a daily limit sized to a normal day's work, not a round number. A paginated pull of per-result data bills a page at a time, so a limit of a few thousand can be reached in minutes.
* Treat `402 DAILY_CREDIT_CAP_REACHED` as "stop until tomorrow", not as a reason to retry: `X-CreditLimit-Daily-Reset` gives the wait in seconds.
* Use bulk endpoints to cut both rate and credit usage.
* Use the free management and Account endpoints for dashboards and monitoring.
* Expect empty results (not errors) when data isn't available.
# Saved Searches
Source: https://api.tryspecter.com/api-ref/saved-searches
Turn filters you've built in the Specter app into a live, queryable feed
A saved search turns a set of filters you've built in the Specter app into a live, queryable feed. Save the search once, share it with the API, and pull its matching companies, people, investors, or signals on demand, including just the ones added since you last looked.
## How it works
There are two ways to get a saved search the API can read.
**From the API.** Run [AI search](/api-reference/search/ai-search), take the `query_id` it returns, and pass it to [Create saved search](/api-reference/saved-searches/create-saved-search) with a name. The search is shared with the API and your organization on creation, so it is readable immediately.
**From the app.** Build the search in the relevant feed, save it as a named search, then open the saved-searches index, click the three-dot menu (⋯) next to it, and turn on "Share to API". A search shared only within your team is not reachable.
Either way, [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches) lists every search the API can see, with its product type and query ID, and you then call the matching "results" endpoint for that product.
To change a search's filters, edit it in the app. The API can create, read and delete a saved search, but not update one.
New to saved searches? Follow the step-by-step walkthrough for building and managing them in the app in the [Saved Searches guide](https://intercom.help/specter-labs/en/collections/6581526-saved-searches) in the Specter Help Center.
## Endpoints
### Discover and manage
| Method | Endpoint | Returns |
| -------- | ------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `GET` | [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches) | Every saved search shared with the API, across all types |
| `POST` | [Create saved search](/api-reference/saved-searches/create-saved-search) | Saves a query under a name and shares it with the API |
| `DELETE` | [Delete search](/api-reference/saved-searches/delete-search) | Permanently deletes a saved search (irreversible) |
### Details and results (by product type)
"Details" gives counts (total matched, newly added, with highlights) cheaply; "results" returns the matching records, paginated.
| Method | Endpoint | Returns |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `GET` | [Get company saved search](/api-reference/company-saved-searches/get-company-saved-search) | Match counts for a company search |
| `GET` | [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results) | The companies matching the search |
| `GET` | [Get people saved search](/api-reference/people-saved-searches/get-people-saved-search) | Match counts for a people search |
| `GET` | [Get people saved search results](/api-reference/people-saved-searches/get-people-saved-search-results) | The people matching the search |
| `GET` | [Get investor saved search](/api-reference/investor-saved-searches/get-investor-saved-search) | Match counts for an investor search |
| `GET` | [Get investor saved search results](/api-reference/investor-saved-searches/get-investor-saved-search-results) | The investors matching the search |
| `GET` | [Get talent signal saved search](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search) | Match counts for a talent search |
| `GET` | [Get talent signal saved search results](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search-results) | Talent signals matching the search |
| `GET` | [Get investor-interest saved search](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search) | Match counts for an interest search |
| `GET` | [Get investor-interest saved search results](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search-results) | Interest signals matching the search |
| `GET` | [Get funding rounds saved search](/api-reference/funding-rounds-saved-searches/get-funding-rounds-saved-search) | Match counts for a funding-rounds search |
| `GET` | [Get funding rounds saved search results](/api-reference/funding-rounds-saved-searches/get-funding-rounds-saved-search-results) | The funding rounds matching the search |
| `GET` | [Get acquisitions saved search](/api-reference/acquisitions-saved-searches/get-acquisitions-saved-search) | Match counts for an acquisitions search |
| `GET` | [Get acquisitions saved search results](/api-reference/acquisitions-saved-searches/get-acquisitions-saved-search-results) | The acquisitions matching the search |
| `GET` | [Get IPOs saved search](/api-reference/ipos-saved-searches/get-ipos-saved-search) | Match counts for an IPOs search |
| `GET` | [Get IPOs saved search results](/api-reference/ipos-saved-searches/get-ipos-saved-search-results) | The IPOs matching the search |
## How to use the API
Get started monitoring a search:
1. **Get a saved search.** Create one with [Create saved search](/api-reference/saved-searches/create-saved-search), or save and share one in the app (see "How it works" above).
2. **Find it.** [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches) → note the `query_id` and product type.
3. **Pull results.** Call the matching results endpoint for that type, paginated.
4. **Poll for new matches.** Pass `new_results_after` with the timestamp of your last read to get only what has been added since — you choose the window, so a scheduled job never double-reads or skips. Every product's results endpoint takes it.
5. **Check counts cheaply.** The "details" endpoint returns total matched / newly added without pulling every record; handy for dashboards.
**Chain into the rest of the API.** Search results carry the underlying IDs; follow them to [Get company by ID](/api-reference/companies/get-company-by-id), [Get person by ID](/api-reference/people/get-person-by-id), [Get investor by ID](/api-reference/investors/get-investor-by-id), or the relevant signal endpoint.
## Good to know
* The API can create, read, query and delete a saved search, but not update one. Editing filters is done in the app.
* A search is reachable when it was created by the API, explicitly shared to the API via "Share to API", or is a global search curated by Specter. A search shared only within your team is not accessible from the API.
* A search created through the API is assigned to an organization admin, returned as `owner_id`, and is visible to your team in the app.
* `new_results_after` (every product) restricts results to what was added to the search from that moment on. Additions are tracked for 60 days; an older cutoff returns `422` rather than a partial answer.
* Results are paginated; empty results are valid, not an error.
* Unknown or non-visible searches return `404`.
# Get API call logs
Source: https://api.tryspecter.com/api-reference/account/get-api-call-logs
/api-ref/bundle_api.yaml get /logs
Returns a paginated log of the API calls your organisation has made, newest first.
Free. This call does not consume credits.
## What you need
Nothing beyond your API key.
## Behaviour
- Ordered newest first.
- Page through with `page` and `limit`.
- Filter by time window with `from` / `to` (ISO 8601 datetime, minute granularity).
- The response carries an `X-Total-Count` header and RFC 5988 `Link` pagination links.
- Each entry includes `credits_consumed` and `request_id`.
## What you do next
- **Chase a specific call.** Quote a log entry's `request_id` when contacting API support to point them at that exact call.
# Get credit balance
Source: https://api.tryspecter.com/api-reference/account/get-credit-balance
/api-ref/bundle_api.yaml get /organization/credits
Returns the calling organization's API credit balance for the current billing window: the provisioned limit, credits used, and credits remaining, plus today's spend against your organization's own daily limit when one is set. This endpoint stays readable when either ceiling is reached, so you can always check where you stand.
Free. This call does not consume credits.
## What you need
Nothing beyond your API key. This call is free.
## Behaviour
Returns your organization's current credit balance, so you can check how many credits remain before running a larger job. It does not consume credits.
`daily_cap`, `daily_used` and `daily_remaining` report your organization's own daily spending limit, which admins set in the API console. `daily_cap` is `0` when no limit is set. See [Rate Limits & Credit Limits](/api-ref/rate_limits) for how the limit behaves.
# Get organization members
Source: https://api.tryspecter.com/api-reference/account/get-organization-members
/api-ref/bundle_api.yaml get /organization/members
Returns all active members of your team: their user ID, role, name, and email.
Free. This call does not consume credits.
## What you need
Nothing beyond your API key.
## Behaviour
- Page through with `page` and `limit`.
- Suspended users are excluded.
- Each member's `user_id` matches the `connected_teammates` values returned by the Network endpoints.
## What you do next
- **Resolve a teammate.** Match a `user_id` to the `connected_teammates` values in [Get network people](/api-reference/network/get-network-people) and [Get network connections at a company](/api-reference/network/get-network-connections-at-a-company) to see who holds a given connection.
# Health check
Source: https://api.tryspecter.com/api-reference/account/health-check
/api-ref/bundle_api.yaml get /health
Returns HTTP `200` with `{"status":"OK"}` while the API is up, serving traffic, and able to reach both of its backing databases.
Free. This call does not consume credits.
## What you need
Nothing. This endpoint is unauthenticated and requires no API key.
## Behaviour
A lightweight status check for uptime monitoring. It returns `200` with `{ "status": "OK" }` when the API is up and both backing databases are reachable. If a database is unreachable it returns `503`, with each dependency reported individually so you can see which is failing.
# Get acquisitions saved search
Source: https://api.tryspecter.com/api-reference/acquisitions-saved-searches/get-acquisitions-saved-search
/api-ref/bundle_api.yaml get /searches/acquisitions/{searchId}
Returns count-level details for a saved acquisitions search: its name, query ID, and the number of acquisitions matched.
Free. This call does not consume credits.
## What you need
A acquisitions saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
## Behaviour
- Returns metadata and counts only (no per-acquisition records); fetch the acquisitions with [Get acquisitions saved search results](/api-reference/acquisitions-saved-searches/get-acquisitions-saved-search-results).
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Must be a acquisitions search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`. The stored product value is `acquisition`.
- Returns `404` if the search doesn't exist or `searchId` is not a number.
## What you do next
- **Pull the records.** Fetch matches with [Get acquisitions saved search results](/api-reference/acquisitions-saved-searches/get-acquisitions-saved-search-results).
# Get acquisitions saved search results
Source: https://api.tryspecter.com/api-reference/acquisitions-saved-searches/get-acquisitions-saved-search-results
/api-ref/bundle_api.yaml get /searches/acquisitions/{searchId}/results
Returns the acquisitions matching a saved acquisitions search.
Costs 1 credit per result returned.
## What you need
An acquisitions saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches), or check counts first with [Get acquisitions saved search](/api-reference/acquisitions-saved-searches/get-acquisitions-saved-search).
## Behaviour
- Each item is the same acquisition object [Get acquisitions by date](/api-reference/transactions/get-acquisitions-by-date) returns, so it parses identically.
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Set `new_results_after` to a timestamp to return only the deals added to the search since then — pass back the timestamp of your last read to poll for what is new. It must be within the last 60 days.
- Must be a acquisitions search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- `searchId` must be a number, otherwise `400` (`BAD_SEARCH_ID_TYPE`); returns `404` if the search doesn't exist.
- A search that matches nothing returns `200` with an empty array, and is not charged.
## What you do next
- **Get the full company.** Follow a `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id) for the complete profile.
- **Open a single deal.** Pass an acquisition ID to [Get acquisition by ID](/api-reference/transactions/get-acquisition-by-id).
# Find company ID
Source: https://api.tryspecter.com/api-reference/companies/find-company-id
/api-ref/bundle_api.yaml post /companies/resolve
Resolve a batch of alternate identifiers (domain, website, LinkedIn, Crunchbase or Pitchbook URL, or company name) into the Specter company `id`. Re-use that `id` with the id-only company endpoints such as [Get company by ID](/api-reference/companies/get-company-by-id).
Free. This call does not consume credits. The id-only endpoints you call next are charged as usual.
## What you need
One or more identifiers to resolve: a domain, website, LinkedIn URL, Crunchbase URL, Pitchbook URL, or company name (1–50 per request). No Specter ID is required; that is what this returns.
## Behaviour
- Pass identifiers under `to_resolve` (1-50 per request). Each entry must carry exactly one identifier; none, or more than one, returns a validation error.
- The response has one result group per input, in the same order, so you can attribute each set of matches back to what you sent. `query` echoes the normalized identifier.
- `domain` matches the primary domain and any domain aliases; `website_url` is reduced to its domain before matching.
- Exact identifiers (`domain`, `website_url`, `linkedin_url`, `crunchbase_url`, `pitchbook_url`) return at most one company, with `match_confidence` `1`.
- `crunchbase_url` must point at an organization profile; `pitchbook_url` at a Pitchbook profile. Both accept `http`/`https`, `www`, query strings and anchors, and are normalized before matching.
- `name` is fuzzy-matched and can return several ranked candidates (at most 10). Each carries a `match_confidence` from 0 to 1, relative to the other results for that query; use the extra fields (domain, HQ, founded year) to pick the right one.
- An identifier that matches nothing keeps its place with an empty `matches` list.
## What you do next
- **Get the full profile.** Pass the returned `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **See who it competes with.** Feed the `company_id` to [Get company competitors](/api-reference/companies/get-company-competitors).
- **Track its news.** Pull [Get company news](/api-reference/companies/get-company-news) for the resolved company.
# Get company acquisitions
Source: https://api.tryspecter.com/api-reference/companies/get-company-acquisitions
/api-ref/bundle_api.yaml get /companies/{companyId}/acquisitions
Returns the acquisitions a company is involved in (both deals where it was the acquirer and deals where it was the acquiree), newest first. Every row carries both sides, so you can tell the direction of each deal. Use either `acquirer_company_id` or `acquiree_company_id` with [Get company by ID](/api-reference/companies/get-company-by-id) to pull the other party's full record.
Costs 1 credit per request, returning up to 50 results per page.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
Narrow the range with `acquired_date_after` / `acquired_date_before`, and walk it with `page` and `limit`.
## Behaviour
- A company can appear as the acquirer on some rows and the acquiree on others.
- Ordered by `acquisition_date` descending, with nulls last.
- Page through results with `limit` and `page` (`page` is zero-based; `limit` defaults to 50, max 50 per page). Up to 1,000 rows are available in total across pages.
- Returns `404` if the company ID doesn't exist. A company with no acquisitions returns `200` with an empty array.
## What you do next
- **Open a deal.** Pull one acquisition's full detail with [Get acquisition by ID](/api-reference/transactions/get-acquisition-by-id).
- **Profile the other party.** Acquisitions carry both company IDs; follow one to [Get company by ID](/api-reference/companies/get-company-by-id).
# Get company by ID
Source: https://api.tryspecter.com/api-reference/companies/get-company-by-id
/api-ref/bundle_api.yaml get /companies/{companyId}
Retrieve the full, current company record for a single Specter company ID. Returns `404` if no company matches the ID.
Costs 1 credit per matched result.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
## What you do next
- **Get the team.** Pull founders and employees with [Get company employees](/api-reference/companies/get-company-employees).
- **See its funding.** Pull round history with [Get company funding rounds](/api-reference/companies/get-company-funding-rounds).
- **Find competitors.** Pull a ranked competitive set with [Get company competitors](/api-reference/companies/get-company-competitors).
# Get company competitors
Source: https://api.tryspecter.com/api-reference/companies/get-company-competitors
/api-ref/bundle_api.yaml post /companies/{companyId}/competitors
Returns the competitive landscape for a company, a ranked list of competitors, the dimensions the market splits on, and a short summary of the competitive landscape.
Costs 1 credit per request, returning up to 30 results. A company with no competitors isn't charged.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
## Behaviour
- Cache-first: a company that's already been analysed returns instantly; one that's never been analysed computes the full landscape on demand and is slower.
- Results older than 30 days are recomputed automatically, so the landscape is never more than 30 days stale. `last_updated` reports when it was last computed.
- At most 30 competitors are returned; `limit` (1–30) only narrows that set; it can't raise the ceiling above 30.
- The request body is optional; omit it to use the default `limit` of 30.
- Returns `404` if the company doesn't exist.
## What you do next
- **Enrich the landscape.** Follow each competitor's `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id) for its full profile.
- **Track the set.** Add the competitors to a company list with [Create company list](/api-reference/company-lists/create-company-list) to monitor them over time.
# Get company employees
Source: https://api.tryspecter.com/api-reference/companies/get-company-employees
/api-ref/bundle_api.yaml get /companies/{companyId}/people
Returns the people Specter has on file for a company (founders and employees) as a list. Each row carries the person's identity, socials, location, highlights and signal IDs alongside their role at the company; use `person_id` with [Get person by ID](/api-reference/people/get-person-by-id) for the full profile (experience, education, skills).
Costs 1 credit per request, returning up to 50 results per page.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
Walk the results with `page` and `limit`.
## Behaviour
- Returns at most 50 people per request
- Narrow results with `founders`, `ceo`, `key_people`, and `department`; these filters can be combined.
- Page through large teams with `limit` and `page` (`page` is zero-based).
- Returns `404` if the company ID doesn't exist.
## What you do next
- **Profile a person.** Follow a person's `person_id` to [Get person by ID](/api-reference/people/get-person-by-id).
- **Get their email.** Pull a contactable address with [Get person email](/api-reference/people/get-person-email).
- **Watch their moves.** Follow a person's `talent_signal_ids` to [Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date).
# Get company funding rounds
Source: https://api.tryspecter.com/api-reference/companies/get-company-funding-rounds
/api-ref/bundle_api.yaml get /companies/{companyId}/funding-rounds
Returns a company's funding rounds, newest first, each with the round detail and every participating investor (with a lead flag). Use each `investor_id` with [Get investor by ID](/api-reference/investors/get-investor-by-id) to pull a full investor profile.
Costs 1 credit per request, returning up to 50 results per page.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
Narrow the range with `funding_announced_date_after` / `funding_announced_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Ordered by `announced_on` descending; rounds with no announced date come last.
- Page through results with `limit` and `page` (`page` is zero-based; `limit` defaults to 50, max 50 per page). Up to 1,000 rows are available in total across pages.
- Returns `404` if the company ID doesn't exist.
## What you do next
- **Look up an investor.** Each round lists investors with `investor_id` and `is_lead_investor`; follow one to [Get investor by ID](/api-reference/investors/get-investor-by-id).
- **Open a single round.** Pull one round's full detail with [Get funding round by ID](/api-reference/transactions/get-funding-round-by-id).
# Get company investor-interest signals
Source: https://api.tryspecter.com/api-reference/companies/get-company-investor-interest-signals
/api-ref/bundle_api.yaml get /companies/{companyId}/investor-interest-signals
Investor-interest signals attributed to a specific company, newest first: the interest investors have shown in this company. Each item is the same signal object returned by [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date).
Costs 1 credit per result returned.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
Narrow the range with `signal_date_after` / `signal_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Ordered by signal date, newest first, at most 50 results per page.
- Both date bounds are inclusive and each stands alone: send only `signal_date_after` for everything since a date, only `signal_date_before` for everything up to one, or both for a window.
- An unknown company returns `404`; a known company with no signals in range returns `200` with an empty array, and an empty page is not billed.
- This endpoint reports no totals: there is no `X-Total-Count` and no `Link` header, so page until you get back fewer results than you asked for.
## What you do next
- **See who is interested.** `signal_investors` names the investors behind each signal, and each resolves through [Get investor by ID](/api-reference/investors/get-investor-by-id).
- **Get the full company.** Follow the `companyId` to [Get company by ID](/api-reference/companies/get-company-by-id) for the complete profile.
- **Get the full person.** Follow a `person_id` to [Get person by ID](/api-reference/people/get-person-by-id) for the complete profile.
# Get company IPOs
Source: https://api.tryspecter.com/api-reference/companies/get-company-ipos
/api-ref/bundle_api.yaml get /companies/{companyId}/ipos
Returns a company's IPOs, newest first. Most companies have zero or one; dual-listed or re-listed companies may have more. Fetch a single IPO with [Get IPO by ID](/api-reference/transactions/get-ipo-by-id), or the issuing company with [Get company by ID](/api-reference/companies/get-company-by-id).
Costs 1 credit per request, returning up to 50 results per page.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
Walk the results with `page` and `limit`.
## Behaviour
- Ordered by `went_public_on` descending, with nulls last.
- Page through results with `limit` and `page` (`page` is zero-based; `limit` defaults to 50, max 1000).
- Returns `404` if the company ID doesn't exist. A company with no IPOs returns `200` with an empty array.
## What you do next
- **Open an IPO.** Pull exchange, ticker, and proceeds with [Get IPO by ID](/api-reference/transactions/get-ipo-by-id).
- **See the private raises.** Pull the funding history before listing with [Get company funding rounds](/api-reference/companies/get-company-funding-rounds).
# Get company latest revenue
Source: https://api.tryspecter.com/api-reference/companies/get-company-latest-revenue
/api-ref/bundle_api.yaml get /companies/{companyId}/latest-revenue
Returns the latest revenue figures and estimated revenue growth for a single company.
Costs 1 credit per matched result.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
## Behaviour
- Growth fields are percentages (`4.05` = +4.05%) and can be negative.
- `revenue_type` is the metric the reported figure represents (e.g. `Revenue`, `ARR`).
- A matched company with no revenue data on file returns `200` with every revenue field set to `null`.
- Returns `404` if no company matches `companyId`.
## What you do next
- **See the full history.** Pull every revenue signal, not just the latest, with [Get company revenue signals](/api-reference/companies/get-company-revenue-signals).
- **Get valuation too.** Pull the latest valuation with [Get company latest valuation](/api-reference/companies/get-company-latest-valuation).
# Get company latest valuation
Source: https://api.tryspecter.com/api-reference/companies/get-company-latest-valuation
/api-ref/bundle_api.yaml get /companies/{companyId}/latest-valuation
Returns the latest valuation figures and estimated valuation growth for a single company.
Costs 1 credit per matched result.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
## Behaviour
- Growth fields are percentages (`4.05` = +4.05%) and can be negative.
- Valuation figures are post-money.
- A matched company with no valuation data on file returns `200` with every valuation field set to `null`.
- Returns `404` if no company matches `companyId`.
## What you do next
- **Get revenue too.** Pull the latest revenue with [Get company latest revenue](/api-reference/companies/get-company-latest-revenue).
- **See the raises behind it.** Pull the funding history with [Get company funding rounds](/api-reference/companies/get-company-funding-rounds).
# Get company news
Source: https://api.tryspecter.com/api-reference/companies/get-company-news
/api-ref/bundle_api.yaml get /companies/{companyId}/news-signals
Returns a company's complete news-signal history.
Costs 1 credit per request, returning up to 50 results per page.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
Narrow the range with `news_publication_date_after` / `news_publication_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Sorted reverse-chronologically (most recent first).
- Page through with `page` and `limit`.
- Set `major_only=true` to return only major news (importance score of at least 4).
- Bound results by publication date with `news_publication_date_after` / `news_publication_date_before` (both inclusive).
- Returns `404` when the company is unknown to Specter, and `200` with an empty array when the company is known but has no signals.
## What you do next
- **Get the company profile.** Follow the `companyId` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **Narrow the window.** Bound `news_publication_date_after` / `news_publication_date_before` to a period, or set `major_only` to keep only the headline events.
# Get company revenue signals
Source: https://api.tryspecter.com/api-reference/companies/get-company-revenue-signals
/api-ref/bundle_api.yaml get /companies/{companyId}/revenue-signals
Returns a company's complete revenue and profitability signal history.
Costs 2 credits per result returned.
## What you need
A Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
Narrow the range with `revenue_signal_date_after` / `revenue_signal_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Sorted reverse-chronologically (most recent first).
- Page through with `page` and `limit`.
- Bound results by signal date with `revenue_signal_date_after` / `revenue_signal_date_before` (both inclusive). For the current week's signals, set `revenue_signal_date_after` to the Monday.
- Returns `404` when the company is unknown to Specter, and `200` with an empty array when known but with no signals.
## What you do next
- **Check the latest revenue.** Get the company's most recent revenue figure with [Get company latest revenue](/api-reference/companies/get-company-latest-revenue).
- **Check the latest valuation.** Get the most recent valuation with [Get company latest valuation](/api-reference/companies/get-company-latest-valuation).
- **Follow the news.** See what's driving the numbers with [Get company news](/api-reference/companies/get-company-news).
# Create company list
Source: https://api.tryspecter.com/api-reference/company-lists/create-company-list
/api-ref/bundle_api.yaml post /lists/companies
Creates a new company list shared with the API and returns its ID.
Free. This call does not consume credits.
## What you need
A unique list name; optionally the company IDs to seed it.
## Behaviour
- Pass `name` (required); it must be unique.
- Optionally seed the list with `company_ids`.
- Set `is_public` to share the list with your team.
- Add companies later via [Update company list](/api-reference/company-lists/update-company-list).
- The list owner is the first team admin on the account.
## What you do next
- **Add or remove companies.** Update membership with [Update company list](/api-reference/company-lists/update-company-list).
- **Pull the list.** Get its companies with [Get company list results](/api-reference/company-lists/get-company-list-results).
# Delete company list
Source: https://api.tryspecter.com/api-reference/company-lists/delete-company-list
/api-ref/bundle_api.yaml delete /lists/companies/{listId}
Permanently deletes a company list and all its associated data.
Free. This call does not consume credits.
## What you need
A list ID (UUID) shared with the API.
You need a company list ID. Get one from [Get all company lists](/api-reference/company-lists/get-all-company-lists).
## Behaviour
- `listId` must be a UUID, otherwise `400`.
- The list must be shared with the API to be deletable; deleting removes it from users' lists.
- Returns `404` if the list doesn't exist or isn't visible.
- This action cannot be undone.
## What you do next
- **Review your remaining lists.** See what's left with [Get all company lists](/api-reference/company-lists/get-all-company-lists).
# Get all company lists
Source: https://api.tryspecter.com/api-reference/company-lists/get-all-company-lists
/api-ref/bundle_api.yaml get /lists/companies
Returns the company lists reachable from your API key: lists created via the API, lists with "Share to API" turned on, and global lists curated by Specter.
Free. This call does not consume credits.
## What you need
At least one company list reachable from your API key. Create one in the Specter app (then share it with the API from the list's three-dot menu (⋯) by turning on "Share to API"), or via the API with [Create company list](/api-reference/company-lists/create-company-list) (lists created via the API are shared automatically). Global lists curated by Specter are always reachable.
## Behaviour
- Each list object includes the number of companies in the list.
- `is_global` marks a list curated by Specter, and `shared_with` carries the user IDs the list is shared with, or an empty array when it is not shared.
- Lists shared only within your team are not returned.
- To retrieve the company IDs in a list, call [Get company list](/api-reference/company-lists/get-company-list) with that list's ID.
## What you do next
- **Open a list's companies.** Pull them with [Get company list results](/api-reference/company-lists/get-company-list-results).
- **Build a new list.** Create one with [Create company list](/api-reference/company-lists/create-company-list).
# Get company list
Source: https://api.tryspecter.com/api-reference/company-lists/get-company-list
/api-ref/bundle_api.yaml get /lists/companies/{listId}
Returns information about a company list created or shared with the API, including the companies that are part of the list.
Free. This call does not consume credits.
## What you need
You need a company list ID. Get one from [Get all company lists](/api-reference/company-lists/get-all-company-lists).
## Behaviour
- `listId` must be a UUID, otherwise `400`.
- Returns `404` if the list doesn't exist or isn't visible to the API.
## What you do next
- **Get full company data.** Pull profiles and signals via [Get company list results](/api-reference/company-lists/get-company-list-results).
- **Open a single company.** Pass a `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
# Get company list results
Source: https://api.tryspecter.com/api-reference/company-lists/get-company-list-results
/api-ref/bundle_api.yaml get /lists/companies/{listId}/results
Returns the companies in a list along with their current data and signals.
Costs 1 credit per result returned.
## What you need
A list ID (UUID) reachable from your API key.
You need a company list ID. Get one from [Get all company lists](/api-reference/company-lists/get-all-company-lists).
## Behaviour
- `listId` must be a UUID, otherwise `400`.
- Page through with `page` and `limit`.
- The list must be reachable from your API key.
## What you do next
- **Open a single company.** Follow a company `id` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **Track list-wide signals.** Use [Get company news](/api-reference/companies/get-company-news) or [Get company revenue signals](/api-reference/companies/get-company-revenue-signals).
# Update company list
Source: https://api.tryspecter.com/api-reference/company-lists/update-company-list
/api-ref/bundle_api.yaml patch /lists/companies/{listId}
Adds and/or removes company IDs from an existing company list in a single request.
Free. This call does not consume credits.
## What you need
A list ID (UUID) shared with the API, and the company IDs to add and/or remove.
You need a company list ID. Get one from [Get all company lists](/api-reference/company-lists/get-all-company-lists).
## Behaviour
- Provide `add_ids` and/or `delete_ids`; you can send either or both.
- Operations run add-first-then-remove, so an ID in both ends up removed.
- `listId` must be a UUID, otherwise `400`.
- The list must be shared with the API to be modifiable.
## What you do next
- **Check the result.** Pull the updated members with [Get company list results](/api-reference/company-lists/get-company-list-results).
# Get company saved search
Source: https://api.tryspecter.com/api-reference/company-saved-searches/get-company-saved-search
/api-ref/bundle_api.yaml get /searches/companies/{searchId}
Returns count-level details for a saved company search: total companies matched, newly added, and companies with highlights.
Free. This call does not consume credits.
## What you need
A company saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
## Behaviour
- Returns counts only (no per-company records); fetch the companies with [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results).
- The counts describe the whole search and take no query parameters. For the subset added since a moment you choose, read the results with `new_results_after`.
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- `searchId` must be a number, otherwise `400`; returns `404` if the search doesn't exist, and `400` with `NOT_SUPPORTED_PRODUCT` if the search belongs to a non-company product.
## What you do next
- **Pull the companies.** Fetch full records with [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results).
# Get company saved search results
Source: https://api.tryspecter.com/api-reference/company-saved-searches/get-company-saved-search-results
/api-ref/bundle_api.yaml get /searches/companies/{searchId}/results
Returns the companies matching a saved company search.
Costs 1 credit per result returned.
## What you need
A company saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches), or check counts first with [Get company saved search](/api-reference/company-saved-searches/get-company-saved-search).
## Behaviour
- Set `new_results_after` to a timestamp to return only the companies added to the search since then — pass back the timestamp of your last read to poll for what is new. It must be within the last 60 days.
- Page through with `page` and `limit`.
- The saved search must be shared with the API (via "Share to API"), created via the API, or be a global search curated by Specter.
- `searchId` must be a number, otherwise `400`; returns `400` with `NOT_SUPPORTED_PRODUCT` if the search belongs to a non-company product.
## What you do next
- **Open a single company.** Follow a result's `id` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **Save to a list.** Add results with [Create company list](/api-reference/company-lists/create-company-list).
# Enrich companies (bulk)
Source: https://api.tryspecter.com/api-reference/enrich/enrich-companies-bulk
/api-ref/bundle_api.yaml post /companies/by-id/bulk
Enrich up to 50 companies in one request — the bulk counterpart to [Enrich company](/api-reference/enrich/enrich-company). Each lookup object carries one identifier you already hold (website, domain, LinkedIn, or Crunchbase) and comes back as a full company record. No Specter ID is involved: use [Get company by ID](/api-reference/companies/get-company-by-id) when you already have one.
Costs 1 credit per matched result.
## What you need
A JSON array of 1–50 lookup objects, each identifying one company by website, domain, LinkedIn URL/ID, or Crunchbase URL.
## Behaviour
- Provide exactly one identifier per lookup object.
- The response is a flat array of company objects, the same shape as [Enrich company](/api-reference/enrich/enrich-company).
- Identifiers with no match are omitted, so the response can contain fewer items than you sent.
## What you do next
- **Map the competitive set.** Take the returned `id` and pull the company's rivals with [Get company competitors](/api-reference/companies/get-company-competitors).
- **See who works there.** List the team and founders with [Get company employees](/api-reference/companies/get-company-employees).
- **Track revenue momentum.** Pull the company's revenue-signal history with [Get company revenue signals](/api-reference/companies/get-company-revenue-signals).
# Enrich company
Source: https://api.tryspecter.com/api-reference/enrich/enrich-company
/api-ref/bundle_api.yaml post /companies
Look up and enrich companies by a known identifier - website, domain, LinkedIn, Crunchbase, or Pitchbook. Returns the most current data Specter holds for each match.
Costs 1 credit per matched result.
## What you need
One external identifier for the company you already hold: its website, domain, LinkedIn, or Crunchbase URL (or LinkedIn numeric ID). Supply exactly one per request. You don't need a Specter company ID; if you already have one, call [Get company by ID](/api-reference/companies/get-company-by-id) directly.
## Behaviour
- Matching by `domain` includes the primary domain and any domain aliases, so a single request can return more than one company.
- No match returns an empty list, and Specter is notified to begin sourcing that company.
- `last_updated` shows when each company's data was last refreshed.
## What you do next
- **Map the competitive set.** Take the returned `id` and pull the company's rivals with [Get company competitors](/api-reference/companies/get-company-competitors).
- **See who works there.** List the team and founders with [Get company employees](/api-reference/companies/get-company-employees).
- **Check the latest revenue.** Pull the company's most recent revenue figure with [Get company latest revenue](/api-reference/companies/get-company-latest-revenue).
- **Check the latest valuation.** Get the most recent valuation with [Get company latest valuation](/api-reference/companies/get-company-latest-valuation).
# Enrich investor
Source: https://api.tryspecter.com/api-reference/enrich/enrich-investor
/api-ref/bundle_api.yaml get /investors
Looks up investors in the Specter dataset by `website` (domain), `name`, or both, and returns the matching investor records. Use the `investor_id` from a result with [Get investor by ID](/api-reference/investors/get-investor-by-id) for the full profile.
Costs 1 credit per matched result.
## What you need
At least one of `website` (a domain or full URL) or `name`; supplying both narrows the match.
## Behaviour
- This is a lookup, not a single-result fetch: an ambiguous query (e.g. a shared domain) can return multiple investors.
- Lookups are case-insensitive; `website` accepts a full URL or a bare domain (scheme and `www.` are normalised away).
- Returns `404` if nothing matches, and `422` if neither `website` nor `name` is supplied.
## What you do next
- **Explore the portfolio.** Resolve any `portfolio_companies` ID with [Get company by ID](/api-reference/companies/get-company-by-id).
- **Track their deals.** Pull their rounds and co-investors with [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds).
- **Track what they're chasing.** See the companies and people this investor has shown interest in with [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals).
# Enrich investors (bulk)
Source: https://api.tryspecter.com/api-reference/enrich/enrich-investors-bulk
/api-ref/bundle_api.yaml post /investors/by-id/bulk
Enrich up to 50 investors in one request — the bulk counterpart to [Enrich investor](/api-reference/enrich/enrich-investor). Each lookup object carries a website and/or a name and comes back as a full investor record. No Specter ID is involved: use [Get investor by ID](/api-reference/investors/get-investor-by-id) when you already have one.
Costs 1 credit per matched result.
## What you need
At least one of `website` (a domain or full URL) or `name`; supplying both narrows the match.
## Behaviour
- Provide at least one of `website` or `name` per lookup object.
- Lookups that don't resolve are silently omitted, and the response order isn't guaranteed.
## What you do next
- **Get the full profile.** Pass a result's `investor_id` to [Get investor by ID](/api-reference/investors/get-investor-by-id).
- **Explore the portfolio.** Resolve any `portfolio_companies` ID with [Get company by ID](/api-reference/companies/get-company-by-id).
- **Track their deals.** Pull their rounds and co-investors with [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds).
# Enrich people (bulk)
Source: https://api.tryspecter.com/api-reference/enrich/enrich-people-bulk
/api-ref/bundle_api.yaml post /people/by-id/bulk
Enrich up to 50 people in one request — the bulk counterpart to [Enrich person](/api-reference/enrich/enrich-person). Each lookup object carries one LinkedIn identifier you already hold (URL, vanity ID, numeric ID, or URN) and comes back as a full person record. No Specter ID is involved: use [Get person by ID](/api-reference/people/get-person-by-id) when you already have one.
Costs 1 credit per matched result. `queued` rows aren't charged.
## What you need
A JSON array of 1–50 lookup objects, each identifying one person by LinkedIn URL, vanity ID, numeric ID, or URN.
## Behaviour
- Provide exactly one identifier per lookup object.
- Results are returned in input order, so each row maps back to its lookup.
- Each row carries a `status`: `found` (resolved, with the `person` payload) or `queued` (not found; an enrichment was started, poll later).
## What you do next
- **Reach out.** The profile doesn't include a contactable address; get one with [Get person email](/api-reference/people/get-person-email).
# Enrich people by email (bulk)
Source: https://api.tryspecter.com/api-reference/enrich/enrich-people-by-email-bulk
/api-ref/bundle_api.yaml post /people/by-email/bulk
Resolve up to 50 email addresses to people in one request - the bulk counterpart to [Enrich person by email](/api-reference/enrich/enrich-person-by-email). Pass a JSON array of email addresses (1-50). Each match is a full person record, the same object [Get person by ID](/api-reference/people/get-person-by-id) returns, plus the `email` it resolved from and a match confidence `score`.
Costs 2 credits per matched result.
## What you need
A JSON array of 1–50 email addresses.
## Behaviour
- Each match echoes the `email` it resolved, so you can map results back to inputs.
- Emails that don't match a person are silently omitted, and the response order isn't guaranteed.
- Every field of the person record is included, so no follow-up call is needed to read a profile.
## What you do next
- **Open a match's current company.** Resolve an `experience[].company_id` with [Get company by ID](/api-reference/companies/get-company-by-id).
- **Save the results.** Add the matched people to a list you can find with [Create people list](/api-reference/people-lists/create-people-list).
# Enrich person
Source: https://api.tryspecter.com/api-reference/enrich/enrich-person
/api-ref/bundle_api.yaml post /people
Look up and enrich a person by a known LinkedIn identifier - URL, vanity ID, numeric ID, or URN. Returns the most current professional profile - career history, education, skills, languages, and social presence.
Costs 1 credit per matched result. A queued `202` response isn't charged.
## What you need
One LinkedIn identifier for the person: their profile URL, vanity ID, numeric ID, or URN. Supply exactly one per request. You don't need a Specter person ID; if you already have one, call [Get person by ID](/api-reference/people/get-person-by-id) directly.
## Behaviour
- Returns a single person object when matched.
- If the person isn't in the dataset yet, returns `202` and queues them for enrichment; usually available within 24 hours.
- `linkedin_num_id` and `linkedin_urn` lookups only match existing records; they don't trigger enrichment yet.
## What you do next
- **Reach out.** The profile doesn't include a contactable address; get one with [Get person email](/api-reference/people/get-person-email).
# Enrich person by email
Source: https://api.tryspecter.com/api-reference/enrich/enrich-person-by-email
/api-ref/bundle_api.yaml post /people/by-email
Resolves an email address to the most probable Specter person and returns that person's full record, the same object [Get person by ID](/api-reference/people/get-person-by-id) returns, plus the `email` it resolved from and a match confidence `score`.
Costs 2 credits per matched result.
## What you need
An email address.
## Behaviour
- `score` ranges from 1 to 10. A score of 7 or higher is generally a reliable match; treat lower scores with increasing caution.
- The response carries every field of the person record, so no follow-up call is needed to read the profile.
- Returns `204` if the email can't be matched to a person.
## What you do next
- **Open their current company.** Resolve an `experience[].company_id` with [Get company by ID](/api-reference/companies/get-company-by-id).
- **Read their talent signals.** Pass `person_id` to [Get person talent signals](/api-reference/people/get-person-talent-signals).
- **Do it in bulk.** Looking up many addresses? Use [Enrich people by email (bulk)](/api-reference/enrich/enrich-people-by-email-bulk).
# Get funding rounds saved search
Source: https://api.tryspecter.com/api-reference/funding-rounds-saved-searches/get-funding-rounds-saved-search
/api-ref/bundle_api.yaml get /searches/funding-rounds/{searchId}
Returns count-level details for a saved funding rounds search: its name, query ID, and the number of funding rounds matched.
Free. This call does not consume credits.
## What you need
A funding rounds saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
## Behaviour
- Returns metadata and counts only (no per-funding round records); fetch the funding rounds with [Get funding rounds saved search results](/api-reference/funding-rounds-saved-searches/get-funding-rounds-saved-search-results).
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Must be a funding rounds search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`. The stored product value is `funding_rounds`.
- Returns `404` if the search doesn't exist or `searchId` is not a number.
## What you do next
- **Pull the records.** Fetch matches with [Get funding rounds saved search results](/api-reference/funding-rounds-saved-searches/get-funding-rounds-saved-search-results).
# Get funding rounds saved search results
Source: https://api.tryspecter.com/api-reference/funding-rounds-saved-searches/get-funding-rounds-saved-search-results
/api-ref/bundle_api.yaml get /searches/funding-rounds/{searchId}/results
Returns the funding rounds matching a saved funding rounds search.
Costs 1 credit per result returned.
## What you need
A funding-rounds saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches), or check counts first with [Get funding rounds saved search](/api-reference/funding-rounds-saved-searches/get-funding-rounds-saved-search).
## Behaviour
- Each item is the same funding round object [Get funding rounds by date](/api-reference/transactions/get-funding-rounds-by-date) returns, so it parses identically.
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Set `new_results_after` to a timestamp to return only the rounds added to the search since then — pass back the timestamp of your last read to poll for what is new. It must be within the last 60 days.
- Must be a funding rounds search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- `searchId` must be a number, otherwise `400` (`BAD_SEARCH_ID_TYPE`); returns `404` if the search doesn't exist.
- A search that matches nothing returns `200` with an empty array, and is not charged.
## What you do next
- **Get the full company.** Follow a `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id) for the complete profile.
- **Open a single round.** Pass a funding round ID to [Get funding round by ID](/api-reference/transactions/get-funding-round-by-id).
# Get investor-interest saved search
Source: https://api.tryspecter.com/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search
/api-ref/bundle_api.yaml get /searches/investor-interest/{searchId}
Returns count-level details for a saved investor-interest search: its name, query ID, and the number of interest signals matched.
Free. This call does not consume credits.
## What you need
An investor-interest saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
## Behaviour
- Returns metadata and counts only (no per-signal records); fetch the signals with [Get investor-interest saved search results](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search-results).
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Must be an investor-interest search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- `searchId` must be a number, otherwise `400` (`BAD_SEARCH_ID_TYPE`); returns `404` if the search doesn't exist.
## What you do next
- **Pull the records.** Fetch matches with [Get investor-interest saved search results](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search-results).
# Get investor-interest saved search results
Source: https://api.tryspecter.com/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search-results
/api-ref/bundle_api.yaml get /searches/investor-interest/{searchId}/results
Returns the interest signals matching a saved investor-interest search.
Costs 1 credit per result returned.
## What you need
An investor-interest saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches), or check counts first with [Get investor-interest saved search](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search).
## Behaviour
- Page through with `page` and `limit`.
- Set `new_results_after` to a timestamp to return only the signals added to the search since then — pass back the timestamp of your last read to poll for what is new. It must be within the last 60 days.
- Bound results by signal date with `investor_signal_date_after` / `investor_signal_date_before` (both inclusive). These select on when a signal was published, which is a different question from when it joined the search; sending them alongside `new_results_after` applies both.
- Must be an investor-interest search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- Returns `404` if the search doesn't exist or isn't accessible.
## What you do next
- **Open the entity.** Follow `entity_id` to [Get company by ID](/api-reference/companies/get-company-by-id) or [Get person by ID](/api-reference/people/get-person-by-id), depending on `signal_type`.
# Get investor-interest signals by date
Source: https://api.tryspecter.com/api-reference/investor-interest-signals/get-investor-interest-signals-by-date
/api-ref/bundle_api.yaml get /investor-interest
Returns investor-interest signals, newest first, each capturing the interest investors have in either talent or companies.
Scope the feed one of three ways:
- `search_id`: signals matching a saved search.
- `list_id`: signals for the members of a list.
- neither: the whole dataset as a by-date feed.
Costs 1 credit per result returned.
## What you need
Nothing beyond your API key for the dataset-wide feed. Add `search_id` or `list_id` to scope it, `signal_date_after` / `signal_date_before` to bound the signal date, and `sort` to order the results.
## Behaviour
- Ordered by signal date, newest first, unless `sort` says otherwise.
- `search_id` and `list_id` are alternative scopes rather than filters that combine: `search_id` wins when both are sent.
- Page size depends on the mode. The by-date feed caps a page at 50 however large a `limit` you send; `search_id` and `list_id` honour the full `limit` this endpoint documents.
- Both date bounds are inclusive and apply in all three modes.
- An unknown `search_id` returns `404`. A saved search whose stored filters cannot be parsed returns `500`.
- This endpoint reports no totals: there is no `X-Total-Count` and no `Link` header, so page until you get back fewer results than you asked for.
- A scope with no signals returns `200` with an empty array, and an empty page is not billed.
## What you do next
- **Pull the subject.** A signal is about a company or a person: `company` and `person` carry the resolved entity, and `entity_id` identifies it for [Get company by ID](/api-reference/companies/get-company-by-id) or [Get person by ID](/api-reference/people/get-person-by-id).
- **Pull the interested investors.** `signal_investors` names them, and each resolves through [Get investor by ID](/api-reference/investors/get-investor-by-id).
- **Narrow to one entity.** For signals about a single company or investor, use [Get company investor-interest signals](/api-reference/companies/get-company-investor-interest-signals) or [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals) instead of filtering this feed.
# Create investor list
Source: https://api.tryspecter.com/api-reference/investor-lists/create-investor-list
/api-ref/bundle_api.yaml post /lists/investors
Creates a new investor list shared with the API and returns its ID.
Free. This call does not consume credits.
## What you need
A unique list name; optionally the investor IDs to seed it.
## Behaviour
- Pass `name` (required); it must be unique per organisation.
- Optionally seed the list with `investor_ids`; duplicates are deduplicated server-side.
- Set `is_public` to share the list with your team.
- The list owner is the first team admin on the account.
- A duplicate name returns `409`.
## What you do next
- **Add or remove investors.** Update membership with [Update investor list](/api-reference/investor-lists/update-investor-list).
- **Pull the list.** Get its investors with [Get investor list](/api-reference/investor-lists/get-investor-list).
# Delete investor list
Source: https://api.tryspecter.com/api-reference/investor-lists/delete-investor-list
/api-ref/bundle_api.yaml delete /lists/investors/{listId}
Permanently deletes an investor list and all its associated data.
Free. This call does not consume credits.
## What you need
A list ID (UUID) shared with the API.
You need a investor list ID. Get one from [Get all investor lists](/api-reference/investor-lists/get-all-investor-lists).
## Behaviour
- `listId` must be a UUID, otherwise `400`.
- The list must be shared with the API to be deletable; deleting removes it from users' lists.
- Returns `404` if the list doesn't exist or isn't visible.
- This action cannot be undone.
## What you do next
- **See your remaining lists.** Confirm with [Get all investor lists](/api-reference/investor-lists/get-all-investor-lists).
# Get all investor lists
Source: https://api.tryspecter.com/api-reference/investor-lists/get-all-investor-lists
/api-ref/bundle_api.yaml get /lists/investors
Returns the investor lists reachable from your API key: lists created via the API, lists with "Share to API" turned on, and global lists curated by Specter.
Free. This call does not consume credits.
## What you need
At least one investor list reachable from your API key. Create one in the Specter app (then share it with the API from the list's three-dot menu (⋯) by turning on "Share to API"), or via the API with [Create investor list](/api-reference/investor-lists/create-investor-list) (lists created via the API are shared automatically). Global lists curated by Specter are always reachable.
## Behaviour
- Each list object includes the number of investors in the list.
- `is_global` marks a list curated by Specter, and `shared_with` carries the user IDs the list is shared with, or an empty array when it is not shared.
- Lists shared only within your team are not returned.
- To retrieve the investor IDs in a list, call [Get investor list](/api-reference/investor-lists/get-investor-list) with that list's ID.
## What you do next
- **Open a list's investors.** Get the investor IDs via [Get investor list](/api-reference/investor-lists/get-investor-list), or full profiles via [Get investor list results](/api-reference/investor-lists/get-investor-list-results).
- **Build a new list.** Create one with [Create investor list](/api-reference/investor-lists/create-investor-list).
# Get investor list
Source: https://api.tryspecter.com/api-reference/investor-lists/get-investor-list
/api-ref/bundle_api.yaml get /lists/investors/{listId}
Returns information about an investor list created or shared with the API, including the investors it contains.
Free. This call does not consume credits.
## What you need
You need a investor list ID. Get one from [Get all investor lists](/api-reference/investor-lists/get-all-investor-lists).
## Behaviour
- `listId` must be a UUID, otherwise `400`.
- Returns `404` if the list doesn't exist or isn't visible to the API.
## What you do next
- **Open a single investor.** Pass an `investor_id` to [Get investor by ID](/api-reference/investors/get-investor-by-id).
# Get investor list results
Source: https://api.tryspecter.com/api-reference/investor-lists/get-investor-list-results
/api-ref/bundle_api.yaml get /lists/investors/{listId}/results
Returns the investors in a list with their current profile, activity, and targeting data.
Costs 1 credit per result returned.
## What you need
A list ID (UUID) reachable from your API key.
You need a investor list ID. Get one from [Get all investor lists](/api-reference/investor-lists/get-all-investor-lists).
## Behaviour
- `listId` must be a UUID, otherwise `400`.
- The list must be of product type `investors`; other product types return `400`.
- Page through with `page` and `limit`.
- The list must be reachable from your API key.
## What you do next
- **Open a single investor.** Follow an `investor_id` to [Get investor by ID](/api-reference/investors/get-investor-by-id).
# Update investor list
Source: https://api.tryspecter.com/api-reference/investor-lists/update-investor-list
/api-ref/bundle_api.yaml patch /lists/investors/{listId}
Adds and/or removes investor IDs from an existing investor list in a single request.
Free. This call does not consume credits.
## What you need
A list ID (UUID) shared with the API, and the investor IDs to add and/or remove.
You need a investor list ID. Get one from [Get all investor lists](/api-reference/investor-lists/get-all-investor-lists).
## Behaviour
- Provide `add_ids` and/or `delete_ids`; you can send either or both.
- `listId` must be a UUID, otherwise `400`.
- The list must be shared with the API to be modifiable.
## What you do next
- **Check the result.** Pull the updated members with [Get investor list results](/api-reference/investor-lists/get-investor-list-results).
# Get investor saved search
Source: https://api.tryspecter.com/api-reference/investor-saved-searches/get-investor-saved-search
/api-ref/bundle_api.yaml get /searches/investors/{searchId}
Returns count-level details for a saved investor search: its name, query ID, and the total number of investors matched.
Free. This call does not consume credits.
## What you need
An investor saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
## Behaviour
- Returns metadata and counts only (no per-investor records); fetch the investors with [Get investor saved search results](/api-reference/investor-saved-searches/get-investor-saved-search-results).
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Must be an investor search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- `full_count` may be `null` while the total count is still being computed.
- `searchId` must be numeric; a non-numeric value returns `404`.
## What you do next
- **Pull the records.** Fetch matches with [Get investor saved search results](/api-reference/investor-saved-searches/get-investor-saved-search-results).
# Get investor saved search results
Source: https://api.tryspecter.com/api-reference/investor-saved-searches/get-investor-saved-search-results
/api-ref/bundle_api.yaml get /searches/investors/{searchId}/results
Returns the investors matching a saved investor search, with full profile, activity, targeting, funds, and portfolio detail.
Costs 1 credit per result returned.
## What you need
An investor saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches), or check counts first with [Get investor saved search](/api-reference/investor-saved-searches/get-investor-saved-search).
## Behaviour
- Set `new_results_after` to a timestamp to return only the investors added to the search since then — pass back the timestamp of your last read to poll for what is new. It must be within the last 60 days.
- Page through with `page` and `limit` (`limit` defaults to 50, max 5000).
- Must be an investor search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- Returns `404` if the search doesn't exist or isn't accessible.
## What you do next
- **Open the investor.** Pass an `investor_id` to [Get investor by ID](/api-reference/investors/get-investor-by-id).
- **Follow the money.** Pull an investor's funding history with [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds).
- **See what they're chasing.** Track an investor's interest signals with [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals).
# Find investor ID
Source: https://api.tryspecter.com/api-reference/investors/find-investor-id
/api-ref/bundle_api.yaml post /investors/resolve
Resolve a batch of investor websites and names into the Specter `investor_id`. Re-use that id with the id-only investor endpoints such as [Get investor by ID](/api-reference/investors/get-investor-by-id).
Free. This call does not consume credits. The id-only endpoints you call next are charged as usual.
## What you need
One or more websites and/or names to resolve (1–50 per request). No Specter ID is required; that is what this returns.
## Behaviour
- Pass inputs under `to_resolve` (1–50 per request). Each entry needs at least one of `website` or `name`; an empty entry returns a validation error. Supplying both narrows the match.
- The response has one result group per input, in the same order, so you can attribute each set of matches back to what you sent. `query` echoes the input.
- `website` is reduced to its domain before matching, so a URL with a scheme or `www.` resolves the same as the bare domain.
- `name` is matched case-insensitively and ignores surrounding whitespace. An ambiguous name can match several firms, so use the returned `website`, `hq_location` and `founded_year` to pick the right one.
- An input that matches nothing keeps its place with an empty `matches` list.
## What you do next
- **Get the full profile.** Pass the returned `investor_id` to [Get investor by ID](/api-reference/investors/get-investor-by-id).
- **Track their deals.** Pull their rounds and co-investors with [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds).
- **See what they're circling.** Read [Get investor-interest signals](/api-reference/investors/get-investor-interest-signals) for the resolved firm.
# Get investor by ID
Source: https://api.tryspecter.com/api-reference/investors/get-investor-by-id
/api-ref/bundle_api.yaml get /investors/{investorId}
Returns the full Specter investor record for a single investor ID - profile, activity, targeting, funds, and portfolio companies. Resolve any `portfolio_companies` ID with [Get company by ID](/api-reference/companies/get-company-by-id).
Costs 1 credit per matched result.
## What you need
A Specter investor ID (`inv_…`); get one from [Enrich investor](/api-reference/enrich/enrich-investor) or [Search entities by name](/api-reference/search/search-entities-by-name).
## Behaviour
- `person_id` is set when the investor is an individual (e.g. an angel); `company_id` is set when there's an associated company (e.g. the firm behind a fund). Either, both, or neither may be `null`.
- Returns `404` if the investor ID doesn't exist.
## What you do next
- **Explore the portfolio.** Resolve any `portfolio_companies` ID with [Get company by ID](/api-reference/companies/get-company-by-id).
- **Track their deals.** Pull their funding rounds and co-investors with [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds).
# Get investor funding rounds
Source: https://api.tryspecter.com/api-reference/investors/get-investor-funding-rounds
/api-ref/bundle_api.yaml get /investors/{investorId}/funding-rounds
Returns an investor's funding rounds, newest first. Each round carries the round detail, the company that raised, and the full list of participating investors - so you can see this investor's co-investors on every deal. Use `company_id` with [Get company by ID](/api-reference/companies/get-company-by-id), or any `investor_id` with [Get investor by ID](/api-reference/investors/get-investor-by-id).
Costs 1 credit per request, returning up to 50 results per page.
## What you need
A Specter investor ID (`inv_…`).
## Behaviour
- Ordered by `announced_on` descending; rounds with no announced date come last.
- Page through results with `limit` and `page` (`page` is zero-based; `limit` defaults to 50, max 50 per page). Up to 1,000 rows are available in total across pages.
- Bound results by announced date with `funding_announced_date_after` / `funding_announced_date_before`.
- Returns `404` if the investor ID doesn't exist.
## What you do next
- **Open a company that raised.** Resolve any round's `company_id` with [Get company by ID](/api-reference/companies/get-company-by-id).
- **Profile a co-investor.** Pass any participating `investor_id` to [Get investor by ID](/api-reference/investors/get-investor-by-id).
# Get investor-interest signals
Source: https://api.tryspecter.com/api-reference/investors/get-investor-interest-signals
/api-ref/bundle_api.yaml get /investors/{investorId}/investor-interest-signals
Investor-interest signals attributed to a specific investor, newest first: the interest this investor has shown in talent or companies. Each item is the same signal object returned by [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date).
Costs 1 credit per result returned.
## What you need
A Specter investor ID (`inv_...`), as returned by [Get investor by ID](/api-reference/investors/get-investor-by-id) or any endpoint that carries an `investor_id`. Narrow the range with `signal_date_after` / `signal_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Ordered by signal date, newest first, at most 50 results per page.
- Both date bounds are inclusive and each stands alone: send only `signal_date_after` for everything since a date, only `signal_date_before` for everything up to one, or both for a window.
- An unknown investor returns `404`; a known investor with no signals in range returns `200` with an empty array, and an empty page is not billed.
- This endpoint reports no totals: there is no `X-Total-Count` and no `Link` header, so page until you get back fewer results than you asked for.
## What you do next
- **Pull what they are interested in.** Each signal is about a company or a person: `company` and `person` carry the resolved entity, and `entity_id` identifies it for [Get company by ID](/api-reference/companies/get-company-by-id) or [Get person by ID](/api-reference/people/get-person-by-id).
- **Cross-check against what they funded.** Interest is not investment; use [Get investor funding rounds](/api-reference/investors/get-investor-funding-rounds) for the rounds this investor actually participated in.
- **Widen to the whole dataset.** Drop the investor scope and use [Get investor-interest signals by date](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date).
# Get IPOs saved search
Source: https://api.tryspecter.com/api-reference/ipos-saved-searches/get-ipos-saved-search
/api-ref/bundle_api.yaml get /searches/ipos/{searchId}
Returns count-level details for a saved IPOs search: its name, query ID, and the number of IPOs matched.
Free. This call does not consume credits.
## What you need
A IPOs saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
## Behaviour
- Returns metadata and counts only (no per-IPO records); fetch the IPOs with [Get IPOs saved search results](/api-reference/ipos-saved-searches/get-ipos-saved-search-results).
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Must be a IPOs search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`. The stored product value is `ipo`.
- Returns `404` if the search doesn't exist or `searchId` is not a number.
## What you do next
- **Pull the records.** Fetch matches with [Get IPOs saved search results](/api-reference/ipos-saved-searches/get-ipos-saved-search-results).
# Get IPOs saved search results
Source: https://api.tryspecter.com/api-reference/ipos-saved-searches/get-ipos-saved-search-results
/api-ref/bundle_api.yaml get /searches/ipos/{searchId}/results
Returns the IPOs matching a saved IPOs search.
Costs 1 credit per result returned.
## What you need
An IPOs saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches), or check counts first with [Get IPOs saved search](/api-reference/ipos-saved-searches/get-ipos-saved-search).
## Behaviour
- Each item is the same IPO object [Get IPOs by date](/api-reference/transactions/get-ipos-by-date) returns, so it parses identically.
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Set `new_results_after` to a timestamp to return only the listings added to the search since then — pass back the timestamp of your last read to poll for what is new. It must be within the last 60 days.
- Must be a IPOs search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- `searchId` must be a number, otherwise `400` (`BAD_SEARCH_ID_TYPE`); returns `404` if the search doesn't exist.
- A search that matches nothing returns `200` with an empty array, and is not charged.
## What you do next
- **Get the full company.** Follow a `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id) for the complete profile.
- **Open a single IPO.** Pass an IPO ID to [Get IPO by ID](/api-reference/transactions/get-ipo-by-id).
# Get network companies
Source: https://api.tryspecter.com/api-reference/network/get-network-companies
/api-ref/bundle_api.yaml get /network/companies
Returns all companies where someone in your team's network currently works ordered by number of connections at each company. Each result includes the person IDs of your contacts there.
Costs 1 credit per request, returning up to 50 results per page.
## What you need
To get started, connect your LinkedIn in [your integration settings](https://app.tryspecter.com/settings/integrations/linkedin). That's all you need: the integration enabled and your API key. It works from your own network alone, so your team doesn't need to be connected.
## Behaviour
- Results are ordered by the number of network contacts at each company, descending.
- Page through with `page` and `limit`.
- Use `min_connections` to require a minimum number of contacts.
## What you do next
- **Open the company.** Follow `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **See who you know there.** Get the contacts and their roles with [Get network connections at a company](/api-reference/network/get-network-connections-at-a-company).
# Get network connections at a company
Source: https://api.tryspecter.com/api-reference/network/get-network-connections-at-a-company
/api-ref/bundle_api.yaml get /network/connection/{companyId}
Returns your team's connections at a specific company, who you know there, what roles they hold and which teammates are linked to them.
Costs 1 credit per request, returning up to 50 results per page.
## What you need
To get started, connect your LinkedIn in [your integration settings](https://app.tryspecter.com/settings/integrations/linkedin). You also need a Specter `companyId` in the path. If you only have a domain, website, or name, get the ID first with [Find company ID](/api-reference/companies/find-company-id) (batch, free), or find it by name with [Search entities by name](/api-reference/search/search-entities-by-name).
## Behaviour
- The `companyId` path parameter is required.
- Returns `404` when the org has no resolvable contacts at the requested company.
## What you do next
- **Open a contact's profile.** Pass a contact's `person_id` to [Get person by ID](/api-reference/people/get-person-by-id).
- **Get an email.** Fetch a verified address for a contact with [Get person email](/api-reference/people/get-person-email).
# Get network people
Source: https://api.tryspecter.com/api-reference/network/get-network-people
/api-ref/bundle_api.yaml get /network/people
Returns all people your team is connected to on LinkedIn, deduped across your teammates. Each result includes which teammates hold the connection.
Costs 1 credit per request, returning up to 50 results per page.
## What you need
To get started, connect your LinkedIn in [your integration settings](https://app.tryspecter.com/settings/integrations/linkedin). That's all you need: the integration enabled and your API key. It works from your own network alone, so your team doesn't need to be connected.
## Behaviour
- Page through results with `page` and `limit` (`page` is zero-based; `limit` defaults to 50).
- Filter the connection source with `connected_on`; only `linkedin` is supported today.
## What you do next
- **Open a full profile.** Pass a `person_id` to [Get person by ID](/api-reference/people/get-person-by-id).
- **Get an email.** Fetch a verified address with [Get person email](/api-reference/people/get-person-email).
- **See where they work.** Follow `current_company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
# Create people list
Source: https://api.tryspecter.com/api-reference/people-lists/create-people-list
/api-ref/bundle_api.yaml post /lists/people
Creates a new people list shared with the API and returns its ID.
Free. This call does not consume credits.
## What you need
A unique list name; optionally the person IDs to seed it.
## Behaviour
- Pass `name` (required); it must be unique.
- Optionally seed the list with `people_ids`.
- Set `is_public` to share the list with your team.
- Add people later via [Update people list](/api-reference/people-lists/update-people-list).
- The list owner is the first team admin on the account.
## What you do next
- **Add or remove people.** Update membership with [Update people list](/api-reference/people-lists/update-people-list).
- **Pull the list.** Get its people with [Get people list results](/api-reference/people-lists/get-people-list-results).
# Delete people list
Source: https://api.tryspecter.com/api-reference/people-lists/delete-people-list
/api-ref/bundle_api.yaml delete /lists/people/{listId}
Permanently deletes a people list and all its associated data.
Free. This call does not consume credits.
## What you need
A list ID (UUID) shared with the API.
You need a people list ID. Get one from [Get all people lists](/api-reference/people-lists/get-all-people-lists).
## Behaviour
- `listId` must be a UUID, otherwise `400`.
- The list must be shared with the API to be deletable; deleting removes it from users' lists.
- Returns `404` if the list doesn't exist or isn't visible.
- This action cannot be undone.
## What you do next
- **See your remaining lists.** Confirm with [Get all people lists](/api-reference/people-lists/get-all-people-lists).
# Get all people lists
Source: https://api.tryspecter.com/api-reference/people-lists/get-all-people-lists
/api-ref/bundle_api.yaml get /lists/people
Returns the people lists reachable from your API key: lists created via the API, lists with "Share to API" turned on, and global lists curated by Specter.
Free. This call does not consume credits.
## What you need
At least one people list reachable from your API key. Create one in the Specter app (then share it with the API from the list's three-dot menu (⋯) by turning on "Share to API"), or via the API with [Create people list](/api-reference/people-lists/create-people-list) (lists created via the API are shared automatically). Global lists curated by Specter are always reachable.
## Behaviour
- Each list object includes the number of people in the list.
- `is_global` marks a list curated by Specter, and `shared_with` carries the user IDs the list is shared with, or an empty array when it is not shared.
- Lists shared only within your team are not returned.
- To retrieve the person IDs in a list, call [Get people list](/api-reference/people-lists/get-people-list) with that list's ID.
## What you do next
- **Open a list's people.** Pull them with [Get people list results](/api-reference/people-lists/get-people-list-results).
- **Build a new list.** Create one with [Create people list](/api-reference/people-lists/create-people-list).
# Get people list
Source: https://api.tryspecter.com/api-reference/people-lists/get-people-list
/api-ref/bundle_api.yaml get /lists/people/{listId}
Returns information about a people list created or shared with the API, including the people it contains.
Free. This call does not consume credits.
## What you need
You need a people list ID. Get one from [Get all people lists](/api-reference/people-lists/get-all-people-lists).
## Behaviour
- `listId` must be a UUID, otherwise `400`.
- Returns `404` if the list doesn't exist or isn't visible to the API.
## What you do next
- **Get full people data.** Pull profiles via [Get people list results](/api-reference/people-lists/get-people-list-results).
- **Open a single person.** Pass a `person_id` to [Get person by ID](/api-reference/people/get-person-by-id).
# Get people list results
Source: https://api.tryspecter.com/api-reference/people-lists/get-people-list-results
/api-ref/bundle_api.yaml get /lists/people/{listId}/results
Returns the people in a list with detailed profile information for each person.
Costs 1 credit per result returned.
## What you need
A list ID (UUID) reachable from your API key.
You need a people list ID. Get one from [Get all people lists](/api-reference/people-lists/get-all-people-lists).
## Behaviour
- `listId` must be a UUID, otherwise `400`.
- Page through with `page` and `limit`.
- The list must be reachable from your API key.
## What you do next
- **Open a single person.** Follow a `person_id` to [Get person by ID](/api-reference/people/get-person-by-id).
- **Get an email.** Fetch a verified address with [Get person email](/api-reference/people/get-person-email).
# Update people list
Source: https://api.tryspecter.com/api-reference/people-lists/update-people-list
/api-ref/bundle_api.yaml patch /lists/people/{listId}
Adds and/or removes person IDs from an existing people list in a single request.
Free. This call does not consume credits.
## What you need
A list ID (UUID) shared with the API, and the person IDs to add and/or remove.
You need a people list ID. Get one from [Get all people lists](/api-reference/people-lists/get-all-people-lists).
## Behaviour
- Provide `add_ids` and/or `delete_ids`; you can send either or both.
- `listId` must be a UUID, otherwise `400`.
- The list must be shared with the API to be modifiable.
## What you do next
- **Check the result.** Pull the updated members with [Get people list results](/api-reference/people-lists/get-people-list-results).
# Get people saved search
Source: https://api.tryspecter.com/api-reference/people-saved-searches/get-people-saved-search
/api-ref/bundle_api.yaml get /searches/people/{searchId}
Returns count-level details for a saved people search: its name, query ID, and the number of people matched.
Free. This call does not consume credits.
## What you need
A people saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
## Behaviour
- Returns metadata and counts only (no per-person records); fetch the people with [Get people saved search results](/api-reference/people-saved-searches/get-people-saved-search-results).
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Must be a people search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- Returns `404` if the search doesn't exist.
## What you do next
- **Pull the records.** Fetch matches with [Get people saved search results](/api-reference/people-saved-searches/get-people-saved-search-results).
# Get people saved search results
Source: https://api.tryspecter.com/api-reference/people-saved-searches/get-people-saved-search-results
/api-ref/bundle_api.yaml get /searches/people/{searchId}/results
Returns the people matching a saved people search.
Costs 1 credit per result returned.
## What you need
A people saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches), or check counts first with [Get people saved search](/api-reference/people-saved-searches/get-people-saved-search).
## Behaviour
- Set `new_results_after` to a timestamp to return only the people added to the search since then — pass back the timestamp of your last read to poll for what is new. It must be within the last 60 days.
- Page through with `page` and `limit`.
- Must be a people search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- Returns `404` if the search doesn't exist or isn't accessible.
## What you do next
- **Open the profile.** Pass a `person_id` to [Get person by ID](/api-reference/people/get-person-by-id).
- **Get an email.** Fetch a verified address with [Get person email](/api-reference/people/get-person-email).
# Find person ID
Source: https://api.tryspecter.com/api-reference/people/find-person-id
/api-ref/bundle_api.yaml post /people/resolve
Resolve a batch of LinkedIn identifiers (profile URL, vanity id, numeric id, or URN) into the Specter `person_id`. Re-use that id with the id-only people endpoints such as [Get person by ID](/api-reference/people/get-person-by-id).
Free. This call does not consume credits. The id-only endpoints you call next are charged as usual.
## What you need
One or more LinkedIn identifiers to resolve (1–50 per request). No Specter ID is required; that is what this returns.
## Behaviour
- Pass identifiers under `to_resolve` (1–50 per request). Each entry must carry exactly one identifier; none, or more than one, returns a validation error.
- The response has one result group per input, in the same order, so you can attribute each result back to what you sent. `query` echoes the identifier.
- Every identifier form addresses a single profile, so `matches` holds at most one person.
- An identifier Specter doesn't hold keeps its place with an empty `matches` list. Nothing is enriched — use [Enrich person](/api-reference/enrich/enrich-person) when you want the profile fetched.
## What you do next
- **Get the full profile.** Pass the returned `person_id` to [Get person by ID](/api-reference/people/get-person-by-id).
- **Reach out.** Get a verified address with [Get person email](/api-reference/people/get-person-email).
- **Watch for moves.** Pull their signal history with [Get person talent signals](/api-reference/people/get-person-talent-signals).
# Get person by ID
Source: https://api.tryspecter.com/api-reference/people/get-person-by-id
/api-ref/bundle_api.yaml get /people/{personId}
Returns the full professional profile for a person - career history, skills, education, and contact links - identified by their Specter person ID.
Costs 1 credit per matched result.
## What you need
A Specter person ID. Resolve one from an email with [Enrich person by email](/api-reference/enrich/enrich-person-by-email), or from a LinkedIn identifier with [Enrich person](/api-reference/enrich/enrich-person); a company's team also carries `person_id` on every row via [Get company employees](/api-reference/companies/get-company-employees).
## Behaviour
- Returns the single most current profile for the ID.
- Returns `404` if the person ID doesn't exist.
## What you do next
- **Get their email.** Fetch a verified address with [Get person email](/api-reference/people/get-person-email).
- **See where they work.** Follow a role's `company_id` in `experience` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **Save them to a list.** Add the person to a list you can find with [Get all people lists](/api-reference/people-lists/get-all-people-lists).
# Get person email
Source: https://api.tryspecter.com/api-reference/people/get-person-email
/api-ref/bundle_api.yaml get /people/{personId}/email
Returns a contactable email for a person, found via a waterfall across multiple data providers. Use the optional type parameter to request a professional or personal email. If you omit it, the endpoint returns a professional email where available, otherwise a personal one. Each response states which type it returned.
Costs 2 credits per matched result.
## What you need
A Specter person ID. Resolve one from an email with [Enrich person by email](/api-reference/enrich/enrich-person-by-email), or from a LinkedIn identifier with [Enrich person](/api-reference/enrich/enrich-person); a company's team also carries `person_id` on every row via [Get company employees](/api-reference/companies/get-company-employees).
## Behaviour
- Returns a single email with its `type` (`professional` or `personal`).
- Returns `204` if the person exists but no email is available.
- Returns `404` if the person ID doesn't exist.
## What you do next
- **Open the full profile.** Get career history, skills, and education with [Get person by ID](/api-reference/people/get-person-by-id).
# Get person talent signals
Source: https://api.tryspecter.com/api-reference/people/get-person-talent-signals
/api-ref/bundle_api.yaml get /people/{personId}/talent-signals
Talent signals attributed to a specific person, newest first: their complete signal history. Each item is the same object returned by [Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date): the signal detail (type, status, score, and stealth timing) plus the person's full professional profile.
Costs 1 credit per result returned.
## What you need
A Specter person ID. Resolve one from an email with [Enrich person by email](/api-reference/enrich/enrich-person-by-email), or from a LinkedIn identifier with [Enrich person](/api-reference/enrich/enrich-person); a company's team also carries `person_id` on every row via [Get company employees](/api-reference/companies/get-company-employees).
Narrow the range with `signal_date_after` / `signal_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Ordered by signal date, newest first, at most 50 results per page.
- Both date bounds are inclusive and each stands alone: send only `signal_date_after` for everything since a date, only `signal_date_before` for everything up to one, or both for a window.
- An unknown person returns `404`; a known person with no signals in range returns `200` with an empty array, and an empty page is not billed.
- This endpoint reports no totals: there is no `X-Total-Count` and no `Link` header, so page until you get back fewer results than you asked for.
## What you do next
- **Pull either employer.** `new_position_company_id` and `past_position_company_id` both work with [Get company by ID](/api-reference/companies/get-company-by-id), so you can see where the person moved to and where they came from.
- **Widen to the whole dataset.** Drop the person scope and use [Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date) to watch every person at once.
# Get revenue signals by date
Source: https://api.tryspecter.com/api-reference/revenue-signals/get-revenue-signals-by-date
/api-ref/bundle_api.yaml get /revenue-signals
Returns revenue and profitability signals across companies, newest first.
Costs 2 credits per result returned.
## What you need
Nothing beyond your API key. Optionally bound the window with `revenue_signal_date_after` / `revenue_signal_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Sorted newest first.
- Page through with `page` and `limit`.
- Bound results by signal date with `revenue_signal_date_after` / `revenue_signal_date_before` (both inclusive). For the current week's signals, set `revenue_signal_date_after` to the Monday.
## What you do next
- **Open a single signal.** Pass a `signal_id` to [Get revenue signals by date](/api-reference/revenue-signals/get-revenue-signals-by-date).
- **Open the company.** Follow a signal's `entity_id` (when set) to [Get company by ID](/api-reference/companies/get-company-by-id).
# Create saved search
Source: https://api.tryspecter.com/api-reference/saved-searches/create-saved-search
/api-ref/bundle_api.yaml post /searches
Saves an existing query under a name so its results can be read later.
Free. This call does not consume credits.
## What you need
A `query_id`, which [AI search](/api-reference/search/ai-search) returns for every query it resolves, and a name.
## Behaviour
- The product is taken from the saved query, not the request, so a saved search and its filters cannot disagree about which product they describe. Sending a `product_type` is rejected with `422`.
- The search is shared with the API and with your organization on creation, so it appears in [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches) immediately and is visible to your team in the app.
- The search is assigned to an admin of your organization, returned as `owner_id`. You do not choose the owner: only an admin-owned search can be deleted through the API, so any other owner would leave a search you cannot remove. An organization with no admin gets a `422`.
- A name the owner has already used returns `409`.
- An unknown `query_id` returns `404`.
## What you do next
- **Read the results.** Take the returned `id` and call the matching product's results endpoint.
- **Remove it.** Delete it with [Delete search](/api-reference/saved-searches/delete-search).
# Delete search
Source: https://api.tryspecter.com/api-reference/saved-searches/delete-search
/api-ref/bundle_api.yaml delete /searches/{searchId}
Permanently deletes a saved search and all its associated data.
Free. This call does not consume credits.
## What you need
A saved search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
## Behaviour
- The search must be shared with the API.
- `searchId` must be a number, otherwise `400`.
- Returns `404` if the search doesn't exist.
- This action cannot be undone; deleting removes the search from users' saved searches.
## What you do next
- **Confirm what's left.** Check your remaining searches with [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
# Get all saved searches
Source: https://api.tryspecter.com/api-reference/saved-searches/get-all-saved-searches
/api-ref/bundle_api.yaml get /searches
Returns your saved searches across all product types.
Free. This call does not consume credits.
## What you need
At least one saved search shared with the API. Either create one with [Create saved search](/api-reference/saved-searches/create-saved-search), or create a search in the Specter app and share it from the saved-searches index via the three-dot menu (⋯) and "Share to API". Global searches curated by Specter are always reachable.
## Behaviour
- Returns searches across every product type: `company`, `people`, `investors`, `talent`, `stratintel` (Investor Interest Signals), `funding_rounds`, `acquisition` and `ipo`.
- Each carries a `product_type`, a `query_id`, `full_count` / `new_count`, and `is_global`, which is `true` for searches curated by Specter.
- Searches shared only within your team or organization are not returned.
- Use a search's `id` with the matching product's results endpoint to fetch results.
## What you do next
- **Query a search's results.** Take a search's `id` and call the matching product's results endpoint: [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results), [Get people saved search results](/api-reference/people-saved-searches/get-people-saved-search-results), [Get investor saved search results](/api-reference/investor-saved-searches/get-investor-saved-search-results), [Get talent signal saved search results](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search-results), or [Get investor-interest saved search results](/api-reference/investor-interest-saved-searches/get-investor-interest-saved-search-results).
- **Remove one.** Delete a search you no longer need with [Delete search](/api-reference/saved-searches/delete-search).
# AI search
Source: https://api.tryspecter.com/api-reference/search/ai-search
/api-ref/bundle_api.yaml post /search
Search Specter with a plain-English query. Describe what you're looking for,
such as "high-growth fintech companies in Germany founded after 2022" or "VC
investors focused on climate", and the endpoint turns it into a structured
search and returns the matching records.
Costs 1 credit for every 5 results returned, rounded up.
## What you need
A plain-English query. Optionally set `product` to force which product to
search; omit it and Specter infers the best product from your query. No IDs
or prior setup are required.
## Supported products and return types
All eight products are searchable, and each result is the same object that
product's own endpoints return, so you parse it the same way. Pass a
`product` value to get the matching object:
| `product` | Returns |
| --- | --- |
| `company` | [Company](/api-reference/companies/get-company-by-id) |
| `people` | [Person](/api-reference/people/get-person-by-id) |
| `investors` | [Investor](/api-reference/investors/get-investor-by-id) |
| `talent_signals` | [Talent signal](/api-reference/talent-signals/get-talent-signals-by-date) |
| `interest_signals` | [Investor-interest signal](/api-reference/investor-interest-signals/get-investor-interest-signals-by-date) |
| `funding_rounds` | [Funding round](/api-reference/transactions/get-funding-round-by-id) |
| `acquisitions` | [Acquisition](/api-reference/transactions/get-acquisition-by-id) |
| `ipos` | [IPO](/api-reference/transactions/get-ipo-by-id) |
## Supported filters
Any filter a product supports can be expressed in the query: geography,
sector, growth stage, funding, headcount, revenue, seniority, dates,
"similar to" a company, and "backed by" an investor.
User-scoped filters aren't supported. The API runs at the organization level, not per user, so filters like "your network," "your CRM," or "your saved lists" won't work. Requests using them return a `422` error. Remove these filters and use standard attributes instead.
## Behaviour
- The search is organization-scoped. It is not saved as a saved search, but the
response returns a `query_id` that identifies the structured filters the query
resolved to (identical queries share an id).
- Results are paginated like the other reads: 50 to a page, walked with
`page` and `limit`, and a `limit` above 50 is rejected with a `422` rather
than quietly trimmed. Paging a query returns the same result set, so a
record does not move between pages as you walk them.
- The bill follows the results, not the request: every 5 results returned
costs 1 credit, rounded up. A full page of 50 costs 10, three results cost
1, and a query that matches nothing costs nothing.
- The number of records that matched overall is returned on the body
(`total_count`) and in the `X-Total-Count` response header, alongside
`X-Page`, `X-Page-Size`, `X-Total-Pages` and a `Link` header.
- `query` must be non-empty, and an unknown `product` value is rejected with a
`422`.
## What you do next
- **Get the full record.** Every result carries its ID. Pass it to that
product's by-ID endpoint: a `company` result to
[Get company by ID](/api-reference/companies/get-company-by-id), an
`investors` result to
[Get investor by ID](/api-reference/investors/get-investor-by-id).
- **Save results to a list.** Add companies with
[Create company list](/api-reference/company-lists/create-company-list),
or people with
[Create people list](/api-reference/people-lists/create-people-list).
# Search entities by name
Source: https://api.tryspecter.com/api-reference/search/search-entities-by-name
/api-ref/bundle_api.yaml get /entities/search
Fuzzy-match one name across companies, people, and investors in a single call, with matches grouped by entity type. This is the unified replacement for the per-type name searches.
Free. This call does not consume credits.
## What you need
Nothing beyond your API key. Pass a `query` with the name you're searching for. This call is free.
## Behaviour
Returns fuzzy name matches across companies, people and investors, each with a `match_confidence`. Only matches above the confidence threshold are returned, and a query with no match returns an empty list. It is a catalogue lookup and never triggers enrichment.
## What you do next
- **Pull the full record.** Take a match's ID and load the profile with [Get company by ID](/api-reference/companies/get-company-by-id), [Get person by ID](/api-reference/people/get-person-by-id) or [Get investor by ID](/api-reference/investors/get-investor-by-id).
# Get talent signal saved search
Source: https://api.tryspecter.com/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search
/api-ref/bundle_api.yaml get /searches/talent/{searchId}
Returns count-level details for a saved talent search: its name, query ID, and the number of talent signals matched.
Free. This call does not consume credits.
## What you need
A talent saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).
## Behaviour
- Returns metadata and counts only (no per-signal records); fetch the signals with [Get talent signal saved search results](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search-results).
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- Must be a talent search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- `searchId` must be a number, otherwise `400` (`BAD_SEARCH_ID_TYPE`); returns `404` if the search doesn't exist.
## What you do next
- **Pull the records.** Fetch matches with [Get talent signal saved search results](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search-results).
# Get talent signal saved search results
Source: https://api.tryspecter.com/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search-results
/api-ref/bundle_api.yaml get /searches/talent/{searchId}/results
Returns the talent signals matching a saved talent search.
Costs 1 credit per result returned.
## What you need
A talent saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches), or check counts first with [Get talent signal saved search](/api-reference/talent-signals-saved-searches/get-talent-signal-saved-search).
## Behaviour
- Page through with `page` and `limit`.
- Set `new_results_after` to a timestamp to return only the signals added to the search since then — pass back the timestamp of your last read to poll for what is new. It must be within the last 60 days.
- Bound results by signal date with `talent_signal_date_after` / `talent_signal_date_before` (both inclusive). These select on when a signal was published, which is a different question from when it joined the search; sending them alongside `new_results_after` applies both.
- Must be a talent search, otherwise `400` with `NOT_SUPPORTED_PRODUCT`.
- Returns `404` if the search doesn't exist or isn't accessible.
## What you do next
- **Open the person.** Pass a `person_id` to [Get person by ID](/api-reference/people/get-person-by-id).
- **Read the signal.** Pass a `talent_signal_id` to [Get talent signals by date](/api-reference/talent-signals/get-talent-signals-by-date).
# Get talent signals by date
Source: https://api.tryspecter.com/api-reference/talent-signals/get-talent-signals-by-date
/api-ref/bundle_api.yaml get /talent
Returns talent signals across all people, newest first. Each item is the same object returned by [Get person talent signals](/api-reference/people/get-person-talent-signals): the signal detail (type, status, score, and stealth timing) plus the full professional profile of the person it's about.
Costs 1 credit per result returned.
## What you need
Nothing beyond your API key — the feed spans every person. Narrow it with `signal_date_after` / `signal_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Ordered by signal date, newest first, at most 50 results per page.
- Both date bounds are inclusive and each stands alone: send only `signal_date_after` for everything since a date, only `signal_date_before` for everything up to one, or both for a window.
- This feed reports no totals: there is no `X-Total-Count` and no `Link` header, so page until you get back fewer results than you asked for.
- A range with no signals returns `200` with an empty array, and an empty page is not billed.
- Each row is a full person profile, not a stub, so a page of 25 signals is 25 credits and a sizeable payload. Bound the date range before widening the page.
## What you do next
- **Pull the person.** Take `person_id` to [Get person by ID](/api-reference/people/get-person-by-id), or to [Get person talent signals](/api-reference/people/get-person-talent-signals) for that person's whole signal history.
- **Pull either employer.** `new_position_company_id` and `past_position_company_id` both work with [Get company by ID](/api-reference/companies/get-company-by-id), so you can look at where someone moved to and where they came from.
- **Poll for new signals.** Re-run with `signal_date_after` set to your last poll date to collect only what has appeared since.
# Get acquisition by ID
Source: https://api.tryspecter.com/api-reference/transactions/get-acquisition-by-id
/api-ref/bundle_api.yaml get /acquisitions/{acquisitionId}
Returns a single acquisition record by its Specter acquisition ID, covering both sides of the deal: the acquirer and the acquiree, each with their Specter company ID and primary domain.
Costs 1 credit per matched result.
## What you need
An acquisition ID in the path. You'll find one on [Get company by ID](/api-reference/companies/get-company-by-id), [Get company acquisitions](/api-reference/companies/get-company-acquisitions), or [Get acquisitions by date](/api-reference/transactions/get-acquisitions-by-date).
## Behaviour
- `acquisitionId` (`acq_…`) is required.
- Returns a single acquisition object.
- Returns `404` if no acquisition with that ID exists.
## What you do next
- **Open the acquirer.** Follow `acquirer_company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **Open the acquiree.** Follow `acquiree_company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
# Get acquisitions by date
Source: https://api.tryspecter.com/api-reference/transactions/get-acquisitions-by-date
/api-ref/bundle_api.yaml get /acquisitions
Returns acquisitions across all companies, newest first. Each item is the same `PublicAcquisition` object returned by [Get acquisition by ID](/api-reference/transactions/get-acquisition-by-id): every row carries both sides of the deal (the acquirer and the acquiree), each with their Specter company ID and primary domain so you can chain to [Get company by ID](/api-reference/companies/get-company-by-id) for either party.
Costs 1 credit per request, returning up to 50 results per page.
## What you need
Nothing beyond your API key — the feed spans every company. Narrow it with `acquired_date_after` / `acquired_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Ordered by acquisition date, newest first, at most 50 results per page.
- Both date bounds are inclusive and each stands alone: send only `acquired_date_after` for everything since a date, only `acquired_date_before` for everything up to one, or both for a window.
- Every response carries `X-Total-Count`, `X-Page`, `X-Page-Size`, `X-Total-Pages` and a `Link` header, so you can size a range before paging through it.
- A range with no acquisitions returns `200` with an empty array, and an empty page is not billed.
## What you do next
- **Pull either side of the deal.** Take `acquirer_company_id` or `acquiree_company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **Re-read one row.** Take `acquisition_id` to [Get acquisition by ID](/api-reference/transactions/get-acquisition-by-id).
- **Poll for new deals.** Re-run with `acquired_date_after` set to your last poll date to collect only what has been announced since.
# Get funding round by ID
Source: https://api.tryspecter.com/api-reference/transactions/get-funding-round-by-id
/api-ref/bundle_api.yaml get /funding-rounds/{fundingRoundId}
Returns a single funding round by its Specter funding round ID, including the company that raised the round and the full list of participating investors, each flagged if they led.
Costs 1 credit per matched result.
## What you need
A funding round ID in the path. You'll find one on [Get company by ID](/api-reference/companies/get-company-by-id), [Get company funding rounds](/api-reference/companies/get-company-funding-rounds), or [Get funding rounds by date](/api-reference/transactions/get-funding-rounds-by-date).
## Behaviour
- `fundingRoundId` (`fnr_…`) is required.
- Returns `404` if the round doesn't exist.
## What you do next
- **Open the company that raised.** Follow `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **Profile an investor.** Pass any participant's `investor_id` to [Get investor by ID](/api-reference/investors/get-investor-by-id).
# Get funding rounds by date
Source: https://api.tryspecter.com/api-reference/transactions/get-funding-rounds-by-date
/api-ref/bundle_api.yaml get /funding-rounds
Returns funding rounds across all companies, newest first, each with the round detail and every participating investor (with a lead flag). Use each `investor_id` with [Get investor by ID](/api-reference/investors/get-investor-by-id) to pull a full investor profile.
Costs 1 credit per request, returning up to 50 results per page.
## What you need
Nothing beyond your API key — the feed spans every company. Narrow it with `announced_date_after` / `announced_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Ordered by announced date, newest first, at most 50 results per page.
- Both date bounds are inclusive and each stands alone: send only `announced_date_after` for everything since a date, only `announced_date_before` for everything up to one, or both for a window.
- Every response carries `X-Total-Count`, `X-Page`, `X-Page-Size`, `X-Total-Pages` and a `Link` header, so you can size a range before paging through it.
- A range with no rounds returns `200` with an empty array, and an empty page is not billed.
## What you do next
- **Pull the company that raised.** Take `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **Pull the investors.** Each entry in `investors` carries an `investor_id` for [Get investor by ID](/api-reference/investors/get-investor-by-id), and a lead flag so you can tell who led the round.
- **Poll for new rounds.** Re-run with `announced_date_after` set to your last poll date to collect only what has been announced since.
# Get IPO by ID
Source: https://api.tryspecter.com/api-reference/transactions/get-ipo-by-id
/api-ref/bundle_api.yaml get /ipos/{ipoId}
Returns a single IPO record by its Specter IPO ID, including the issuing company's Specter company ID and primary domain.
Costs 1 credit per matched result.
## Behaviour
- `ipoId` (`ipo_…`) is required.
- Many IPO fields are nullable when the underlying disclosure wasn't available (e.g. private listings without a published share price).
- Returns `404` if no IPO with that ID exists.
## What you do next
- **Open the issuing company.** Follow `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
# Get IPOs by date
Source: https://api.tryspecter.com/api-reference/transactions/get-ipos-by-date
/api-ref/bundle_api.yaml get /ipos
Returns IPOs across all companies, newest first. Each item is the same `PublicIpo` object returned by [Get IPO by ID](/api-reference/transactions/get-ipo-by-id), including the issuing company's Specter company ID and primary domain so you can chain to [Get company by ID](/api-reference/companies/get-company-by-id).
Costs 1 credit per request, returning up to 50 results per page.
## What you need
Nothing beyond your API key — the feed spans every company. Narrow it with `listed_date_after` / `listed_date_before`, and walk it with `page` and `limit`.
## Behaviour
- Ordered by listing date, newest first, at most 50 results per page.
- Both date bounds are inclusive and each stands alone: send only `listed_date_after` for everything since a date, only `listed_date_before` for everything up to one, or both for a window.
- Every response carries `X-Total-Count`, `X-Page`, `X-Page-Size`, `X-Total-Pages` and a `Link` header, so you can size a range before paging through it.
- A range with no IPOs returns `200` with an empty array, and an empty page is not billed.
## What you do next
- **Pull the issuer.** Take `company_id` to [Get company by ID](/api-reference/companies/get-company-by-id).
- **Re-read one row.** Take `ipo_id` to [Get IPO by ID](/api-reference/transactions/get-ipo-by-id).
- **Poll for new listings.** Re-run with `listed_date_after` set to your last poll date to collect only what has listed since.