> ## 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.
# Enrich 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 person returned.
## 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.
## OpenAPI
````yaml /api-ref/bundle_api.yaml post /people
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:
/people:
post:
tags:
- Enrichment
summary: Enrich people
description: >
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 person returned.
## 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.
requestBody:
description: >
Supply exactly one identifier. Providing more than one returns a
validation error.
required: true
content:
application/json:
schema:
type: object
properties:
linkedin_url:
description: >
The person's LinkedIn profile URL. Accepts `http`/`https`,
with or without `www`.
type: string
linkedin_id:
description: >
The person's LinkedIn vanity ID — the slug at the end of
their profile URL (e.g. `john-doe-123abc` in
`linkedin.com/in/john-doe-123abc`).
type: string
linkedin_num_id:
description: The person's LinkedIn numeric member ID.
type: integer
linkedin_urn:
description: >
The person's LinkedIn URN — a stable, non-changing reference
found in many datasets.
type: string
additionalProperties: false
example:
linkedin_url: https://www.linkedin.com/in/kilianthalhammer
responses:
'200':
$ref: '#/components/responses/PersonResponse'
'202':
description: >
The person wasn't found in the dataset and has been queued for
enrichment, usually completed within 24 hours.
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A message about whether the value has been seen before.
context:
type: object
description: Information about the request and the enrichment.
properties:
id:
type: string
format: uuid
description: A UUID for the enrichment, usable to check its status.
status:
type: string
enum:
- PENDING
- QUEUED
- FAILED
description: How far along the enrichment is.
updatedAt:
type: string
description: When the status was last updated.
'400':
$ref: '#/components/responses/EnrichmentBadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
responses:
PersonResponse:
description: >
A successful response containing the detailed professional profile of
the requested person.
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
EnrichmentBadRequest:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
errorCode:
type: string
description: The type of error.
message:
type: string
description: >
A message with information about why the request was bad, will
be either a single message, or a path to the validation
issues.
examples:
no-request-body:
summary: No request body
value:
errorCode: VALIDATION_ERROR
message: Cannot get item with no request body.
bad-linkedin-id:
summary: Bad LinkedIn Id
value:
errorCode: VALIDATION_ERROR
message: >
{"code":"invalid_type","expected":"number","received":"string","path":["linkedin_id"],"message":"Expected
number, received string"}
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
schemas:
Person:
title: Person
properties:
person_id:
description: >-
The Specter person ID for this person, can be used in people
endpoints.
type: string
example: per_7f8d9e2a1b3c4d5e6f7g8h9i0
talent_signal_ids:
description: Talent signal IDs for this person, can be used in talent endpoints
nullable: true
items:
type: string
example: 02d32673-f1ab-40a1-93c5-a3a36a10d342
type: array
investor_signal_ids:
nullable: true
items:
description: >
Investor signal IDs for this person, will be usable in investor
endpoints when available.
type: string
example: 0340bac8-bcee-46a2-94bf-cf77e0c34253
type: array
profile_picture_url:
description: A url for a profile picture if there is one.
nullable: true
type: string
example: >-
https://peopledb-public.s3.eu-west-2.amazonaws.com/assets/profile-pictures/per_7f8d9e2a1b3c4d5e6f7g8h9i0.jpg
first_name:
description: First name
type: string
example: Sarah
last_name:
description: Last Name
type: string
example: Chen
full_name:
description: Full name
type: string
example: Sarah Chen
linkedin_url:
description: URL for LinkedIn account.
type: string
example: https://www.linkedin.com/in/sarahchen9776
linkedin_num_id:
description: The numeric ID for the LinkedIn account.
type: number
example: 9365023
linkedin_urn:
description: The URN from LinkedIn for the account.
type: string
example: ACABCDEefghijklmnopqurfABCDefghijklnmop
twitter_url:
description: URL for Twitter account.
nullable: true
type: string
example: https://twitter.com/sarahchen9776
github_url:
description: URL for Github account.
nullable: true
type: string
example: https://github.com/sarahchen9776
about:
description: A description of the person.
nullable: true
type: string
example: >-
AI/ML researcher and entrepreneur with a focus on computer vision
applications. Previously led ML teams at Google and founded an AI
startup.
tagline:
description: A shorter tagline for the person.
nullable: true
type: string
example: AI Researcher | Ex-Google | Founder of VisionAI (Acquired by NVIDIA)
location:
description: Where the person is located.
nullable: true
type: string
example: San Francisco, California, United States, North America
region:
description: Main region where the person is located.
nullable: true
type: string
example: North America
highlights:
items:
type: string
example: prior_exit
type: array
description: |
Type of highlight, the full list will be added shortly.
example:
- prior_exit
- prior_vc_backed_experience
- prior_vc_backed_founder
- serial_founder
level_of_seniority:
description: Top level of seniority the person has achieved.
nullable: true
type: string
example: Executive Level
years_of_experience:
description: Years of experience the person has worked for.
nullable: true
type: number
example: 12
education_level:
description: Top level of education that the person has.
nullable: true
type: string
example: Ph.D.
experience:
type: array
description: Companies that the person has worked for.
items:
$ref: '#/components/schemas/Experience'
current_position_title:
description: Title of the person's current position
nullable: true
type: string
example: Senior Research Scientist
current_position_company_name:
description: Name of the company where the person currently works.
nullable: true
type: string
example: Google AI
current_position_company_website:
description: Website for the company where the person currently works.
nullable: true
type: string
example: ai.google.com
past_position_title:
description: Title of the person's last position
nullable: true
type: string
example: Founder & CEO
past_position_company_name:
description: Name of the company where the person last left.
nullable: true
type: string
example: VisionAI
past_position_company_website:
description: Website for the company where the person last left.
nullable: true
type: string
example: visionai.com
current_tenure:
description: Length of time the person has been in their current job.
nullable: true
type: number
example: 3
average_tenure:
description: Average length of time in a position.
nullable: true
type: number
example: 18
education:
type: array
description: Educational background for the person
items:
$ref: '#/components/schemas/Education'
languages:
description: Languages that the person speaks
nullable: true
type: array
items:
$ref: '#/components/schemas/Language'
example:
- name: English
proficiency_level: Native Or Bilingual Proficiency
- name: Mandarin Chinese
proficiency_level: Limited Working Proficiency
skills:
items:
type: string
example: Machine Learning
description: List of skills that the person has.
type: array
example:
- Machine Learning
- Computer Vision
- Deep Learning
- Python
- TensorFlow
- PyTorch
linkedin_followers:
description: Number of followers the person has on LinkedIn.
type: number
example: 8756
linkedin_connections:
description: Number of connections the person has on LinkedIn.
type: number
example: 3421
last_updated:
description: |
A date for when the person was last updated in Specter.
Uses the format YYYY-MM-DD HH:MM:SS.
type: string
example: '2025-01-01 14:40:56'
required:
- person_id
- talent_signal_ids
- profile_picture_url
- first_name
- last_name
- full_name
- linkedin_url
- twitter_url
- about
- tagline
- location
- region
- highlights
- level_of_seniority
- years_of_experience
- education_level
- experience
- past_position_title
- past_position_company_name
- past_position_company_website
- current_tenure
- average_tenure
- education
- languages
- skills
- linkedin_followers
- linkedin_connections
additionalProperties: false
type: object
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
Experience:
properties:
company_name:
title: Experience.company_name
description: The name of the company or organization
type: string
example: Google AI
company_id:
title: Experience.company_id
description: Unique identifier for the company in the system
nullable: true
type: string
example: 5e3a7f2b0aa7a3270a55f2a8
domain:
title: Experience.domain
description: The company's website domain
nullable: true
type: string
example: ai.google.com
linkedin_url:
title: Experience.linkedin_url
description: LinkedIn URL for the company
nullable: true
type: string
example: linkedin.com/company/google
description:
title: Experience.description
description: Details about the role, responsibilities, and achievements
nullable: true
type: string
example: >-
Lead research initiatives in computer vision and deep learning.
Developed novel architectures for image recognition that improved
accuracy by 15%. Mentor junior researchers and collaborate with
product teams to integrate ML models into Google products.
company_size:
title: Experience.company_size
description: The size category of the company
nullable: true
type: string
example: 10001+
industry:
$ref: '#/components/schemas/Industry'
tech_verticals:
$ref: '#/components/schemas/TechVertical'
industries:
anyOf:
- items:
type: string
example: Information Technology
type: array
example:
- Information Technology
- Software
- Artificial Intelligence
- Internet Services
- nullable: true
description: '[Deprecated] Use the `industry` and `tech_verticals`'
deprecated: true
title:
title: Experience.title
description: Job title or position held
type: string
example: Senior Research Scientist
departments:
anyOf:
- items:
title: Experience.departments.[]
type: string
example: Engineering
title: Experience.departments.[]
type: array
example:
- Senior Leadership
- Engineering
- title: Experience.departments
nullable: true
title: Experience.departments
description: Departments or teams the person worked in
start_date:
title: Experience.start_date
description: Start date of the position
nullable: true
type: string
example: '2020-03-01'
end_date:
title: Experience.end_date
description: End date of the position (null if current)
nullable: true
type: string
example: null
location:
title: Experience.location
description: Location where the work was performed
nullable: true
type: string
example: Mountain View, California, United States, United States
is_current:
title: Experience.is_current
description: Whether this is the person's current position
type: boolean
example: true
founded_year:
title: Experience.founded_year
description: The year the company was founded
nullable: true
type: number
example: 1998
job_order:
title: Experience.job_order
description: >-
Sequential order of this job in the person's career (higher numbers
for more recent positions)
type: number
example: 3
required:
- company_name
- linkedin_url
- industries
- title
- departments
- start_date
- is_current
- job_order
additionalProperties: false
title: Experience
type: object
Education:
properties:
name:
title: Education.name
description: The name of the educational institution
nullable: true
type: string
example: Stanford University
linkedin_url:
title: Education.linkedin_url
description: LinkedIn URL for the educational institution
nullable: true
type: string
example: linkedin.com/school/stanford-university
field_of_study:
title: Education.field_of_study
description: The academic field or major area of study
nullable: true
type: string
example: Computer Science
degree_title:
title: Education.degree_title
description: The type of degree or qualification obtained
nullable: true
type: string
example: Ph.D.
description:
title: Education.description
description: >-
Additional details about the educational experience, research focus,
or achievements
nullable: true
type: string
example: >-
Dissertation focused on computer vision and deep learning
algorithms. Published 15 papers in top-tier ML conferences including
NIPS and ICML. Teaching assistant for Advanced Machine Learning
course.
start_date:
title: Education.start_date
description: The start date of the educational program
nullable: true
type: string
example: '2008-01-01'
end_date:
title: Education.end_date
description: The end date or graduation date of the educational program
nullable: true
type: string
example: '2013-01-01'
location:
title: Education.location
description: The location of the educational institution
nullable: true
type: string
example: Stanford, California, United States, United States
required:
- name
- linkedin_url
- field_of_study
- degree_title
- description
- start_date
- end_date
- location
additionalProperties: false
title: Education
type: object
Language:
properties:
name:
title: Language.name
description: The name of the language
nullable: true
type: string
example: Mandarin Chinese
proficiency_level:
title: Language.proficiency_level
description: The level of proficiency in the language
nullable: true
type: string
example: Limited Working Proficiency
required:
- name
- proficiency_level
additionalProperties: false
title: Language
type: object
Industry:
type: array
items:
type: string
example: Financial Services
example:
- Financial Services
- Financial Technology
description: >
Classifies companies by their economic activity — the market they serve
and the products or services they deliver.
E.g: Construction, Utilities, Wholesale.
There is one industry per company, with up to three levels.
nullable: true
TechVertical:
type: array
items:
type: array
items:
type: string
example: Blockchain, Crypto & Web3
example:
- - Blockchain, Crypto & Web3
- Crypto Exchanges and Trading Infrastructure
title: Experience.tech_verticals
description: >
Classifies companies by the technology domain they operate in — the
technical capability or space they're building around.
E.g: AI & Machine Learning, Cybersecurity, FinTech.
There can be up to 5 tech verticals per company, with 2 levels each.
nullable: true
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
````