Skip to main content

​
v3 Migration

v3 is built on a refreshed dataset with ~98% fewer duplicate and corrupted profiles. The team-network Network Mapper has been renamed to Relationships and is free to call. A separate partner-only Network Mapper endpoint replaces the v2 partner network endpoint. Two fields are removed from Fetch Profile (connections, notes), and new profile fields are added (hiring, open_to_work, start_date_confidence, current_company_logo_url, plus company.logo_url on each experience entry).Full details: Migrating to v3.
v3 is now live. v2 endpoints will be deprecated on July 15, EOD UTC.
Only 8 endpoints move to v3: profile/company search and fetch, Relationships, Network Mapper (Partner), and the two status endpoints. Everything else (Social, on-demand Refresh, Team, Credits, MCP) stays on its current path. See the endpoint mapping table.
Some v2 IDs have been removed in v3, and some profiles re-added under new IDs. If a v2 ID no longer exists in v3, the Fetch endpoint returns a standard 404. See Migrating to v3 for the transition behavior.

​
General

Generate your key from Team Settings → API. Full walkthrough in the Quickstart.
See Rate Limiting for current limits.
Yes. Our on-demand scraping system supports scheduled refreshes for selected profiles on a weekly or monthly basis. See Refresh a Profile.
Null values are omitted by default.
Data is sourced from multiple vendors, each with their own update schedules. Job changes are detected continuously — see Daily Job Changes for freshness targets (90% updated within 7 days of a change).
Each connection lists one or more sources, each with an origin describing how the connection was discovered.
Heads up — two different origin vocabularies. The values below describe the response-side connections[].sources[].origin field. If you’re building a query against team_connections.origins, that field uses a different value set — see the Relationships examples for the query vocabulary.
In v3, accepted response-side origin values:
  • linkedin_connection — connection imported from LinkedIn
  • work_overlap — derived from shared work history (overlapping employer + dates)
  • education_overlap — derived from shared education (same school + graduation year)
  • shared_investor — derived from shared investors (shared portfolio companies)
  • email_contact — imported from email contacts
  • calendar_events — imported from calendar events
  • manual_import — connections added manually by a team member
In v2, each source also carries a network field (e.g. google, linkedin, investor-data) alongside origin. v3 returns only origin.

​
Data & Coverage

Fresh data is available daily. Job changes typically range from 10k–50k profiles per day.
We use an internal deduplication algorithm to merge duplicates. v3 eliminated ~98% of the duplicate and corrupted profiles that existed in v2.
We target accuracy within 14 days of a job change. 90% of the database is updated within 7 days of a detected change. See Daily Job Changes for the full freshness model.
Within a major version, yes — IDs are persistent for both people and companies. v3 introduced new IDs for some profiles; see Migrating to v3.
No. Phone numbers are not on the roadmap.
No. We do not track gender, ethnicity, or other diversity-related data.
No. Employment type is not part of the default public profile, so coverage in ethical sources is very limited.
Yes. LinkedIn URLs are generated from the username, ensuring consistency.
Yes. If a person has a job description on LinkedIn, it’s available in our data.
Yes. In v3, the profile includes profile_info.current_company_logo_url for the current company, and each experience entry includes experience[].company.logo_url. Both are CDN URLs.
Both are booleans on profile_info. hiring signals the profile is actively hiring; open_to_work signals they’re open to new opportunities. See Profile.
A string field on each experience entry indicating the confidence of the start date. Values: validated or low.
We comply with industry standards and privacy regulations. For data subject requests, see Data Subject Requests.
Yes. Flat files are delivered in batches (typically 100,000 records). See Flat Files.

​
API & Usage

JSON.
Credits are charged based on results returned, not requests made:
  • Profile/Company fetch — 1 credit per record returned
  • Search — Free
  • Relationships (team network) — Free
  • Network Mapper (partner) — 1 credit per non-empty response
  • Refresh a Profile — 3 credits per profile returned
  • Get Profile/Company Posts — 1 credit per 10 posts returned (rounded up, max 10/call)
  • Get Comments / Reactions / Reshares — flat 1 credit per call
  • Failed requests (non-200) — Free
Full breakdown: Credits & Usage. Plans and overage rates: How API Credits Work.
No. Search is free. You’re only charged for the results returned by the Fetch call (1 credit per profile or company record).
Your current usage is visible on the Subscription page (credits used, remaining, and estimated overage). For a breakdown by request type, see the API Usage section of Team Settings. Programmatic access: GET /credits/usage.
Up to 1000 IDs per call for Fetch Profile / Fetch Company. Search also returns up to 1000 IDs per page.
Use the in_network_only: true parameter in Search Profiles, or use the dedicated Relationships endpoint which is free and returns connection details.
Not directly. Fetch profiles with the relevant fields and apply filtering in your downstream processing.
Use POST /v3/profiles/fetch for profiles or POST /v3/companies/fetch for companies.
  • Relationships — returns profiles connected to your own team. Free, synchronous response. Available to all API keys.
  • Network Mapper — maps connections across the partner network. 1 credit per non-empty response. Requires partner permission (returns 403 otherwise).
Yes. The profile document includes a nested team_connections.origins field — query it with a nested query inside the OpenSearch DSL query, typically scoped to your team_connections.team_id. Accepted values (provisional, may change): csv, plugin, overlaps, google, google-calendar, user-profile, manual-csv, education-overlaps, investor-overlaps, manual-url. See Relationships endpoint examples.Note: this is the query-side vocabulary. The response-side connections[].sources[].origin field uses a different set of values — see the sources field FAQ.
Add Connector is generally available and works with any API key — see Add Connector. Removal is not yet automated; contact support@theswarm.com.
Yes, with a partner-level API key. Contact support@theswarm.com to discuss partner access.
Not as a single field, but you can derive tenure from the experience[].start_date and experience[].end_date fields in the Fetch response. In v3, experience[].start_date_confidence indicates how reliable the start date is.
No. Revenue data is not currently planned.

​
Data Quality

Not always. Smaller companies may lack persistent IDs.
Names are user-generated on LinkedIn, so variations exist. Full names may include middle names or initials.
Not directly, but timestamps indicate when updates occurred. The current_job_updated_at field is the primary signal for job-change tracking — see Daily Job Changes.
Example: Sarah was a Client Success Manager at Company A. She moved to Company B in January 2024 with the same title. In March 2024 she updated her public profiles. In July she was promoted to Senior Client Success Manager — published immediately.Sarah’s timestamps:
  • current_job_updated_at — the moment The Swarm detected a change in her primary job. 2024-03-08T... between March and July, then 2024-07-15T... after the promotion.
  • latest_company_change_at — start date (rounded to full months) of the latest company change: 2024-01-01 (when she actually started at Company B).
  • latest_role_change_at — start date of the latest title change: 2024-07-01.
  • job_start_date — the greater of latest_company_change_at and latest_role_change_at.
  • updated_at — technical timestamp of the last update to any field on the profile.
We don’t currently detect or filter fake profiles. We do filter out empty profiles (those missing basic information).
Not a single field. The number of LinkedIn job experiences is available and can help assess completeness. Profiles vary in richness — Name and Company are the minimum required for a profile to be retained, and profiles can be enriched over time.
We only keep companies with high-quality extracted data. We’re continuously expanding company coverage.
Yes. We’re actively working on improvements aimed at increasing work-email availability to up to 80%.
Some people hold multiple degrees. In most cases the array contains a single value.
Our job-change tracking is continuously improving and some gaps exist in historical data. See Daily Job Changes for our current freshness targets.