> ## 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 (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).
## OpenAPI
````yaml /api-ref/openapi.json post /people/by-id/bulk
openapi: 3.1.0
info:
title: Specter API
termsOfService: https://tryspecter.com/terms/
contact:
name: API support
email: api-support@tryspecter.com
version: 1.0.0
servers:
- url: https://app.tryspecter.com/api/v1
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Enrich
description: >-
Look up a company, person, or investor and, if Specter does not already
hold it, fetch it on demand. Includes email-based person enrichment.
- name: Search
description: Find records across every product from a single plain-English query.
- name: Companies
description: >-
Company profiles, funding, headcount, traction, the per-company signals
and sub-resources attached to a single company, and identifier resolution.
- name: People
description: >-
Specter people records: profile data, contact details, and per-person
lookups for a known person ID.
- name: Investors
description: >-
Specter investor records: profile, activity, targeting, funds, portfolio
companies, and the funding rounds they have participated in.
- name: Transactions
description: 'Transaction detail by ID: funding rounds, acquisitions, and IPOs.'
- name: Revenue Signals
description: >-
Revenue and profitability signals: by ID, by date, and for a saved list or
company search.
- name: Talent Signals
description: 'Talent signals: by ID and in bulk by ID.'
- name: Investor Interest Signals
description: 'Investor interest signals: by ID and in bulk by ID.'
- name: Company Lists
description: Create, query, and maintain lists of companies, including their results.
- name: Investor Lists
description: Create, query, and maintain lists of investors, including their results.
- name: People Lists
description: Create, query, and maintain lists of people, including their results.
- name: Saved Searches
description: List and delete searches saved via tryspecter.com.
- name: Company Saved Searches
description: Details and results for saved company searches.
- name: People Saved Searches
description: Details and results for saved people searches.
- name: Investor Saved Searches
description: Details and results for saved investor searches.
- name: Talent Signals Saved Searches
description: Details and results for saved Talent Signals searches.
- name: Investor Interest Saved Searches
description: Details and results for saved Investor Interest Signals searches.
- name: Funding Rounds Saved Searches
description: Details and results for saved funding-round searches.
- name: Acquisitions Saved Searches
description: Details and results for saved acquisition searches.
- name: IPOs Saved Searches
description: Details and results for saved IPO searches.
- name: Network
description: >-
Your team's LinkedIn network: the people and companies your teammates are
connected to, and your reach into a given company.
- name: Account
description: >-
Organisation-level resources: your team's members, API call logs, and
credit balance.
paths:
/people/by-id/bulk:
post:
tags:
- Enrich
summary: Enrich people (bulk)
description: >-
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).
operationId: peopleEnrichmentBulk
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/PeopleEnrichmentBody'
type: array
maxItems: 50
minItems: 1
title: Lookups
examples:
- - linkedin_url: https://www.linkedin.com/in/patrickcollison
- linkedin_url: https://www.linkedin.com/in/dhorowitz
required: true
responses:
'200':
description: >-
One row per lookup, in input order. `found` rows carry the resolved
`person`; `queued` rows carry the `enrichment` request context.
content:
application/json:
schema:
items:
$ref: '#/components/schemas/BulkPersonResultItem'
type: array
title: Response Peopleenrichmentbulk
example:
- status: found
person:
person_id: per_7f8d9e2a1b3c4d5e6f7g8h9i0
full_name: Sarah Chen
linkedin_url: https://www.linkedin.com/in/sarahchen9776
- status: queued
enrichment:
message: Enrichment in progress
'401':
$ref: '#/components/responses/ApiKeyMissingOrApiKeyNotValid'
'402':
$ref: '#/components/responses/OutOfCredits'
'403':
$ref: '#/components/responses/NotPermitted'
'422':
$ref: '#/components/responses/ValidationFailed422'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
PeopleEnrichmentBody:
properties:
linkedin_url:
anyOf:
- type: string
- type: 'null'
title: Linkedin Url
description: >-
The person's LinkedIn profile URL. Accepts `http`/`https`, with or
without `www`.
examples:
- https://www.linkedin.com/in/janedoe
linkedin_id:
anyOf:
- type: string
- type: 'null'
title: 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`).
examples:
- janedoe
linkedin_num_id:
anyOf:
- type: integer
- type: 'null'
title: Linkedin Num Id
description: The person's LinkedIn numeric member ID.
examples:
- 123456789
linkedin_urn:
anyOf:
- type: string
- type: 'null'
title: Linkedin Urn
description: >-
The person's LinkedIn URN - a stable, non-changing reference found
in many datasets.
examples:
- ACoAAAxxxxxxxx
type: object
title: PeopleEnrichmentBody
description: One LinkedIn identifier for a person. Supply exactly one of the fields.
BulkPersonResultItem:
properties:
status:
type: string
enum:
- found
- queued
title: Status
description: >-
`found` when resolved, `queued` when an async enrichment was started
for an unknown person.
person:
anyOf:
- $ref: '#/components/schemas/PublicPersonResponse'
- type: 'null'
description: The resolved person. Present when `status` is `found`.
enrichment:
anyOf:
- $ref: '#/components/schemas/EnrichmentAcceptedResponse'
- type: 'null'
description: Enrichment request context. Present when `status` is `queued`.
type: object
required:
- status
title: BulkPersonResultItem
description: >-
One row of the bulk people-enrichment response.
The call answers 200 whatever each row resolved to; each row is either
`found` or `queued`, and a queued row stays in the response so the
caller
can poll for the enrichment it triggered.
PublicPersonResponse:
properties:
person_id:
type: string
title: Person Id
description: >-
The Specter person ID for this person, can be used in people
endpoints.
examples:
- per_34f8a8ad1f7497b83e821345
talent_signal_ids:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Talent Signal Ids
description: >-
Talent signal IDs for this person. To read the signals themselves,
call Get person talent signals rather than resolving these IDs
individually.
examples:
- - 58323b85-153b-4d3d-8c0c-62dbf41198dc
investor_signal_ids:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Investor Signal Ids
description: >-
Investor-interest signal IDs for this person. There is no per-person
investor-interest endpoint; read these signals from the by-date
feed.
examples:
- - 0340bac8-bcee-46a2-94bf-cf77e0c34253
profile_picture_url:
anyOf:
- type: string
- type: 'null'
title: Profile Picture Url
description: A url for a profile picture if there is one.
examples:
- >-
https://peopledb-public.s3.eu-west-2.amazonaws.com/assets/profile-pictures/per_34f8a8ad1f7497b83e821345.jpg
first_name:
anyOf:
- type: string
- type: 'null'
title: First Name
description: First name
examples:
- Cosmin
last_name:
anyOf:
- type: string
- type: 'null'
title: Last Name
description: Last Name
examples:
- Urdea
full_name:
anyOf:
- type: string
- type: 'null'
title: Full Name
description: Full name
examples:
- Cosmin Urdea
linkedin_url:
anyOf:
- type: string
- type: 'null'
title: Linkedin Url
description: URL for LinkedIn account.
examples:
- https://www.linkedin.com/in/cosmin-urdea-0848973
linkedin_num_id:
anyOf:
- type: integer
- type: 'null'
title: Linkedin Num Id
description: The numeric ID for the LinkedIn account.
examples:
- 11147428
linkedin_urn:
anyOf:
- type: string
- type: 'null'
title: Linkedin Urn
description: The URN from LinkedIn for the account.
examples:
- ACoAAEULqT0BasKeraebkQhLfmIwxpxTlNThQjE
twitter_url:
anyOf:
- type: string
- type: 'null'
title: Twitter Url
description: URL for Twitter account.
examples:
- https://x.com/moissinac
github_url:
anyOf:
- type: string
- type: 'null'
title: Github Url
description: URL for Github account.
examples:
- https://github.com/sarahchen9776
about:
anyOf:
- type: string
- type: 'null'
title: About
description: A description of the person.
examples:
- >-
IT Software Consultant / Contractor 20+ years of experience in
software development - Systems and Applications Architecture -
Product Design / Management - Coach and mentorship.
tagline:
anyOf:
- type: string
- type: 'null'
title: Tagline
description: A shorter tagline for the person.
examples:
- Software Consultant / Contractor
location:
anyOf:
- type: string
- type: 'null'
title: Location
description: Where the person is located.
examples:
- Bucharest, București, Romania, Europe
region:
anyOf:
- type: string
- type: 'null'
title: Region
description: Main region where the person is located.
examples:
- Europe
highlights:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Highlights
description: Type of highlight, the full list will be added shortly.
examples:
- - major_tech_experience
- prior_vc_backed_experience
- strong_technical_background
- vc_backed_experience
level_of_seniority:
anyOf:
- type: string
- type: 'null'
title: Level Of Seniority
description: Top level of seniority the person has achieved.
examples:
- Senior Level
years_of_experience:
anyOf:
- type: integer
- type: 'null'
title: Years Of Experience
description: Years of experience the person has worked for.
examples:
- 21
education_level:
anyOf:
- type: string
- type: 'null'
title: Education Level
description: Top level of education that the person has.
examples:
- ''
experience:
anyOf:
- items:
$ref: '#/components/schemas/PublicExperienceItem'
type: array
- type: 'null'
title: Experience
description: Companies that the person has worked for.
current_position_title:
anyOf:
- type: string
- type: 'null'
title: Current Position Title
description: Title of the person's current position
examples:
- Senior Consultant Fintech & Digital Payment
current_position_company_name:
anyOf:
- type: string
- type: 'null'
title: Current Position Company Name
description: Name of the company where the person currently works.
examples:
- valantic (vormals mm1)
current_position_company_website:
anyOf:
- type: string
- type: 'null'
title: Current Position Company Website
description: Website for the company where the person currently works.
examples:
- mm1.com
past_position_title:
anyOf:
- type: string
- type: 'null'
title: Past Position Title
description: Title of the person's last position
examples:
- Product Owner (Contracted)
past_position_company_name:
anyOf:
- type: string
- type: 'null'
title: Past Position Company Name
description: Name of the company where the person last left.
examples:
- Riverty
past_position_company_website:
anyOf:
- type: string
- type: 'null'
title: Past Position Company Website
description: Website for the company where the person last left.
examples:
- riverty.com
current_tenure:
anyOf:
- type: integer
- type: 'null'
title: Current Tenure
description: Length of time the person has been in their current job.
examples:
- 15
average_tenure:
anyOf:
- type: number
- type: 'null'
title: Average Tenure
description: Average length of time in a position.
examples:
- 22
education:
anyOf:
- items:
$ref: '#/components/schemas/PublicEducationItem'
type: array
- type: 'null'
title: Education
description: Educational background for the person
languages:
anyOf:
- items:
$ref: '#/components/schemas/PublicLanguageItem'
type: array
- type: 'null'
title: Languages
description: Languages that the person speaks
examples:
- - name: English
proficiency_level: Native Or Bilingual Proficiency
- name: Mandarin Chinese
proficiency_level: Limited Working Proficiency
skills:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Skills
description: List of skills that the person has.
examples:
- - API Development
- Agentic AI
- Algorithms
- Apache Spark
linkedin_followers:
anyOf:
- type: integer
- type: 'null'
title: Linkedin Followers
description: Number of followers the person has on LinkedIn.
examples:
- 904
linkedin_connections:
anyOf:
- type: integer
- type: 'null'
title: Linkedin Connections
description: Number of connections the person has on LinkedIn.
examples:
- 500
last_updated:
type: string
title: Last Updated
description: |-
A date for when the person was last updated in Specter.
Uses the format YYYY-MM-DD HH:MM:SS.
examples:
- '2026-07-13 17:37:30'
type: object
required:
- person_id
- last_updated
title: PublicPersonResponse
EnrichmentAcceptedResponse:
properties:
message:
type: string
title: Message
description: A message about whether the value has been seen before.
examples:
- Enrichment in progress
context:
$ref: '#/components/schemas/EnrichmentContext'
type: object
required:
- message
- context
title: EnrichmentAcceptedResponse
ApiKeyMissing:
properties:
errorCode:
type: string
const: API_KEY_MISSING
title: Errorcode
message:
type: string
title: Message
examples:
- No API Key was presented on the header X-API-KEY
type: object
required:
- errorCode
- message
title: ApiKeyMissing
ApiKeyNotValid:
properties:
errorCode:
type: string
const: API_KEY_NOT_VALID
title: Errorcode
message:
type: string
title: Message
examples:
- API key present, but not valid
type: object
required:
- errorCode
- message
title: ApiKeyNotValid
OutOfCredits:
properties:
errorCode:
type: string
enum:
- OUT_OF_CREDITS
- DAILY_CREDIT_CAP_REACHED
title: Errorcode
description: >-
`OUT_OF_CREDITS` when the organization's credit pool is empty;
`DAILY_CREDIT_CAP_REACHED` when the organization's own daily credit
limit has been reached, which clears at 00:00 UTC.
message:
type: string
title: Message
examples:
- There are no more credits available to complete the request
type: object
required:
- errorCode
- message
title: OutOfCredits
NotPermitted:
properties:
errorCode:
type: string
const: NOT_PERMITTED
title: Errorcode
message:
type: string
title: Message
examples:
- API key present, but you are not permitted
type: object
required:
- errorCode
- message
title: NotPermitted
ValidationFailed:
properties:
errorCode:
type: string
const: VALIDATION_ERROR
title: Errorcode
message:
type: string
title: Message
description: >-
Why the request was rejected: each invalid field, with the path to
it.
examples:
- Field required (body.name)
type: object
required:
- errorCode
- message
title: ValidationFailed
RateLimited:
properties:
errorCode:
type: string
const: RATE_LIMITED
title: Errorcode
message:
type: string
title: Message
examples:
- You have been rate-limited
type: object
required:
- errorCode
- message
title: RateLimited
PublicExperienceItem:
properties:
company_name:
anyOf:
- type: string
- type: 'null'
title: Company Name
description: The name of the company or organization
examples:
- valantic (vormals mm1)
company_id:
anyOf:
- type: string
- type: 'null'
title: Company Id
description: Unique identifier for the company in the system
examples:
- 6744b47c776432406530a72b
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
description: The company's website domain
examples:
- mm1.com
linkedin_url:
anyOf:
- type: string
- type: 'null'
title: Linkedin Url
description: LinkedIn URL for the company
examples:
- https://www.linkedin.com/company/mm1
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Details about the role, responsibilities, and achievements
examples:
- >-
As an Implementation Engineer at valantic, I play a pivotal role
in the technical execution of Stripe integration projects,
ensuring precision, efficiency, and robust infrastructure in every
implementation.
company_size:
anyOf:
- type: string
- type: 'null'
title: Company Size
description: The size category of the company
examples:
- 51-200
industry:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Industry
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.
examples:
- - Financial Services
- Financial Technology
tech_verticals:
anyOf:
- items:
items:
type: string
type: array
type: array
- type: 'null'
title: 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.
examples:
- - - Blockchain, Crypto & Web3
- Crypto Exchanges and Trading Infrastructure
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: Job title or position held
examples:
- Senior Consultant Fintech & Digital Payment
departments:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Departments
description: Departments or teams the person worked in
examples:
- - Finance
start_date:
anyOf:
- type: string
- type: 'null'
title: Start Date
description: Start date of the position
examples:
- '2025-04-01'
end_date:
anyOf:
- type: string
- type: 'null'
title: End Date
description: End date of the position (null if current)
examples:
- '2025-03-01'
location:
anyOf:
- type: string
- type: 'null'
title: Location
description: Location where the work was performed
examples:
- Stuttgart, Baden-Wurttemberg, Germany, Europe
is_current:
anyOf:
- type: boolean
- type: 'null'
title: Is Current
description: Whether this is the person's current position
examples:
- true
founded_year:
anyOf:
- type: integer
- type: 'null'
title: Founded Year
description: The year the company was founded
examples:
- 1997
job_order:
anyOf:
- type: integer
- type: 'null'
title: Job Order
description: >-
Sequential order of this job in the person's career (higher numbers
for more recent positions)
examples:
- 13
type: object
title: PublicExperienceItem
PublicEducationItem:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the educational institution
examples:
- Stanford University
linkedin_url:
anyOf:
- type: string
- type: 'null'
title: Linkedin Url
description: LinkedIn URL for the educational institution
examples:
- https://www.linkedin.com/school/stanford-university
field_of_study:
anyOf:
- type: string
- type: 'null'
title: Field Of Study
description: The academic field or major area of study
examples:
- Computer Science (AI track) and Statistics
degree_title:
anyOf:
- type: string
- type: 'null'
title: Degree Title
description: The type of degree or qualification obtained
examples:
- Bachelor of Science - BS
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: >-
Additional details about the educational experience, research focus,
or achievements
examples:
- Krieger School of Arts and Sciences
start_date:
anyOf:
- type: string
- type: 'null'
title: Start Date
description: The start date of the educational program
examples:
- '2024-01-01'
end_date:
anyOf:
- type: string
- type: 'null'
title: End Date
description: The end date or graduation date of the educational program
examples:
- '2028-01-01'
location:
anyOf:
- type: string
- type: 'null'
title: Location
description: The location of the educational institution
examples:
- Stanford, California, United States, North America
type: object
title: PublicEducationItem
PublicLanguageItem:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the language
examples:
- Romanian
proficiency_level:
anyOf:
- type: string
- type: 'null'
title: Proficiency Level
description: The level of proficiency in the language
examples:
- Native Or Bilingual Proficiency
type: object
title: PublicLanguageItem
EnrichmentContext:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: A UUID for the enrichment, usable to check its status.
status:
anyOf:
- type: string
- type: 'null'
title: Status
description: How far along the enrichment is.
examples:
- PENDING
updated_at:
anyOf:
- type: string
- type: 'null'
title: Updated At
description: When the status was last updated.
type: object
title: EnrichmentContext
description: Information about the request and the enrichment.
responses:
ApiKeyMissingOrApiKeyNotValid:
description: Unauthorized
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ApiKeyMissing'
- $ref: '#/components/schemas/ApiKeyNotValid'
OutOfCredits:
description: Out of credits - API credit limit exceeded
headers:
X-CreditLimit-Limit:
description: The total number of credits allocated for the current period
schema:
type: integer
X-CreditLimit-Remaining:
description: The number of credits remaining for the current period
schema:
type: integer
X-CreditLimit-Reset:
description: The number of seconds until the credit limit resets
schema:
type: number
format: float
X-CreditLimit-Daily-Limit:
description: >-
The organization's own daily credit limit. Sent only when one is
set.
schema:
type: integer
X-CreditLimit-Daily-Remaining:
description: >-
The credits left under the daily limit today. Sent only when one is
set.
schema:
type: integer
X-CreditLimit-Daily-Reset:
description: >-
The number of seconds until the daily limit resets at 00:00 UTC.
Sent only when one is set.
schema:
type: number
format: float
content:
application/json:
schema:
$ref: '#/components/schemas/OutOfCredits'
NotPermitted:
description: Forbidden - There is no permissions to use the endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/NotPermitted'
ValidationFailed422:
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationFailed'
RateLimited:
description: Too Many Requests - API Rate limit exceeded
headers:
X-RateLimit-Limit:
description: The total rate limit allowed for this endpoint
schema:
type: integer
X-RateLimit-Remaining:
description: The number of requests remaining
schema:
type: integer
X-RateLimit-Reset:
description: The number of seconds until the rate limit resets
schema:
type: number
format: float
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimited'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.