> ## Documentation Index
> Fetch the complete documentation index at: https://api.tryspecter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Resolve company ID
> Resolve a batch of alternate identifiers — domain, website, LinkedIn 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).
This endpoint is free — resolving identifiers to IDs uses no credits. The id-only endpoints you call next are charged as usual.
## 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`) return at most one company, with `match_confidence` `1`.
- `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.
## OpenAPI
````yaml /api-ref/bundle_api.yaml post /companies/resolve
openapi: 3.0.0
info:
title: Specter API
termsOfService: https://tryspecter.com/terms/
contact:
name: API support
email: api-support@tryspecter.com
version: 1.0.0
servers:
- description: Production
url: https://app.tryspecter.com/api/v1
security:
- ApiKeyAuth: []
tags:
- name: Enrichment
description: >
Endpoints which can be used to query for data and, if the data is not
found request that it be retrieved by Specter systems.
- name: Companies
description: >
Endpoints that provide the most up to date information about all the
companies in our data set. Giving the ability to query by a specific
company id, or using a keyword such as the domain.
This also allows us to enrich the data about a company if we either do not
have it or it is older than expected, which means you always have the most
up-to-date information possible.
- name: People
description: >
Endpoints that expose Specter people records — profile data and contact
details — for a known person ID.
- name: Investors
description: >
Endpoints that expose Specter investor records — profile, activity,
targeting, funds, portfolio companies, and the funding rounds they have
participated in — for a known investor ID.
- name: Talent and Interest Signals
description: >
Endpoints for retrieving Specter Talent Signals and Investor Interest
Signals by ID.
- name: News Signals
description: >
Company-level news signals generated from articles monitored by Specter.
Each signal represents a single classified company mention within an
article and includes a summary of the newsworthy update (such as funding,
deals, revenue, profitability, or traction) along with an assigned
importance score.
- name: Revenue Signals
description: >
Revenue and profitability observations for companies, derived from news
coverage and public filings. Each signal captures one data point — the
revenue or profitability metric, the year it refers to, the source, and
the company it is attributed to.
- name: Transactions
description: >
Endpoints that expose transaction detail — funding rounds, acquisitions,
and IPOs — by ID.
- name: Company Lists
description: >
Create, query and maintain lists of companies that are of particular
interest. The endpoints here allow you to interrogate and maintain those
lists using a programmatic interface.
- name: People Lists
description: >
Create, query and maintain lists of people that are of particular
interest. The endpoints here allow you to interrogate and maintain those
lists using a programmatic interface.
- name: Investor Lists
description: >
Create, query and maintain lists of investors that are of particular
interest. The endpoints here allow you to interrogate and maintain those
lists using a programmatic interface.
- name: Network
description: >
Endpoints for accessing your team's LinkedIn network - the people and
companies your teammates are connected to.
- name: Saved Searches
description: >
Manage searches that have been saved via `tryspecter.com`. These endpoints
are useful to programmatically list and delete saved searches. To update a
search the UI should be used at `tryspecter.com`.
- name: Company Saved Searches
description: >
Query and get results for company searches that have been saved via
`tryspecter.com`. These endpoints are useful to programmatically get
results and information for a search. To update a search the UI should be
used at `tryspecter.com`.
- name: People Saved Searches
description: >
Query and get results for people searches that have been saved via
`tryspecter.com` or via the API. These endpoints are useful to
programmatically get results and information for a search. To update a
search the UI should be used at `tryspecter.com`.
- name: Investor Saved Searches
description: >
Query and inspect saved investor searches — metadata (name, match counts)
and paginated results — from searches saved via `tryspecter.com` or shared
with the API.
- name: Talent Signals Saved Searches
description: >
Query and get results for Talent Signals searches that have been saved via
`tryspecter.com`.
- name: Investor Interest Saved Searches
description: >
Query and get results for Investor Interest Signals searches that have
been saved via `tryspecter.com`.
- name: Organization
description: >
Endpoints for accessing your organization's members and org-level
resources.
- name: Customer Data
description: >
Retrieve a log of API calls made by your organization. Useful for auditing
usage, debugging integrations, and monitoring activity.
paths:
/companies/resolve:
post:
tags:
- Companies
summary: Resolve company ID
description: >
Resolve a batch of alternate identifiers — domain, website, LinkedIn
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).
This endpoint is free — resolving identifiers to IDs uses no
credits. The id-only endpoints you call next are charged as usual.
## 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`) return at
most one company, with `match_confidence` `1`.
- `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.
requestBody:
description: The identifiers to resolve.
required: true
content:
application/json:
schema:
type: object
properties:
to_resolve:
type: array
minItems: 1
maxItems: 50
items:
$ref: '#/components/schemas/CompanyResolveIdentifier'
required:
- to_resolve
additionalProperties: false
example:
to_resolve:
- domain: tryspecter.com
- name: Rippling
responses:
'200':
$ref: '#/components/responses/CompanyResolveResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'422':
description: >
`to_resolve` is missing or empty, or an item provides no identifier,
more than one, or a malformed value (e.g. a `name` shorter than 3
characters).
'429':
$ref: '#/components/responses/RateLimits'
components:
schemas:
CompanyResolveIdentifier:
type: object
description: >
One alternate company identifier. Supply exactly one of the fields
below; providing none, or more than one, returns a validation error.
properties:
website_url:
description: |
Company website. Accepts `http`/`https`, with or without `www`.
type: string
domain:
description: >
Company domain or a domain alias — e.g. `tryspecter.com` resolves to
Specter.
type: string
linkedin_url:
description: |
Company LinkedIn URL. Accepts `http`/`https`, with or without `www`.
type: string
name:
description: >
Company name (at least 3 characters). Fuzzy-matched; may return
several ranked candidates.
type: string
additionalProperties: false
title: CompanyResolveIdentifier
BasicCompany:
type: object
properties:
id:
description: The Specter company ID; use it with the other company endpoints.
type: string
example: 5e3a8f19040ca7b0c6f03082
name:
description: The company's main public name.
type: string
example: Rippling
domain:
description: The domain of the website, can have a sub-domain.
type: string
example: rippling.com
hq:
$ref: '#/components/schemas/HQ'
description: The company's HQ location.
tagline:
description: A concise description of what the company does.
type: string
example: Workforce management that unifies HR, IT, and finance.
founded_year:
description: The year the company was founded.
type: number
nullable: true
example: 2016
match_confidence:
description: >
How closely the company matches the query, from 0 to 1. Relative to
the other results in this response; not comparable across searches.
type: number
example: 0.8
required:
- id
- name
- hq
- match_confidence
additionalProperties: false
ApiKeyMissing:
properties:
errorCode:
description: API_KEY_MISSING
example: API_KEY_MISSING
type: string
message:
description: No API Key was presented on the header X-API-KEY
example: No API Key was presented on the header X-API-KEY
type: string
ApiKeyNotValid:
properties:
errorCode:
description: API_KEY_NOT_VALID
example: API_KEY_NOT_VALID
type: string
message:
description: API key present, but not valid
example: API key present, but not valid
type: string
HQ:
properties:
city:
description: City for the location.
type: string
example: London
state:
description: >-
State for the location, outside of America will relate to the
country and region.
type: string
example: England
country:
description: Country for the location.
type: string
example: United Kingdom
region:
description: Use `continent` instead.
type: string
example: Europe
deprecated: true
continent:
description: The continent the HQ is in.
type: string
example: Europe
regions:
description: Any regions that the HQ is in.
type: array
items:
type: string
example:
- London Metropolitan Area
- EMEA
required:
- city
- state
- country
- region
additionalProperties: false
title: HQ
type: object
responses:
CompanyResolveResponse:
description: >
One result group per input identifier, in the same order as
`to_resolve`.
content:
application/json:
schema:
type: array
items:
type: object
properties:
query:
$ref: '#/components/schemas/CompanyResolveIdentifier'
description: The (normalized) identifier this group resolves.
matches:
description: >
Matching companies. Empty when nothing matched; several
ranked candidates are possible for a `name` query.
type: array
items:
$ref: '#/components/schemas/BasicCompany'
required:
- query
- matches
additionalProperties: false
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiKeyMissing'
- $ref: '#/components/schemas/ApiKeyNotValid'
Forbidden:
description: Forbidden - There is no permissions to use the endpoint
content:
application/json:
schema:
type: object
properties:
errorCode:
description: NOT_PERMITTED
type: string
example: NOT_PERMITTED
message:
type: string
description: You do not have permission to access this resource.
example: You do not have permission to access this resource.
required:
- errorCode
- message
RateLimits:
description: Too Many Requests - API Rate limit exceeded
content:
application/json:
schema:
type: object
required:
- errorCode
- message
properties:
errorCode:
type: string
description: RATE_LIMITED
message:
type: string
description: You have been rate-limited
headers:
X-RateLimit-Limit:
schema:
type: integer
description: The total rate limit allowed for this endpoint
X-RateLimit-Remaining:
schema:
type: integer
description: The number of requests remaining
X-RateLimit-Reset:
schema:
type: number
format: float
description: The number of seconds until the rate limit resets
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
````