Skip to main content
The Swarm API v3 is built on a refreshed underlying dataset and includes a renamed endpoint, a new partner endpoint, removed fields on Fetch Profile, and several new fields.
v2 endpoints will be deprecated on July 15, EOD UTC. Migrate to v3 before then to avoid service interruption.

​
Why v3

  • ~98% reduction in duplicate and corrupted profiles
  • All upcoming data quality improvements will only ship to v3

​
Timeline

​
Endpoint mapping

Only 8 endpoints move to v3. Everything else stays on its current path.

​
Staying on v2

These endpoints are not moving to v3 — keep using the current paths:
  • All /social/... endpoints (post comments, reactions, reshares, profile posts, company posts)
  • GET /v2/profiles/fetch/refresh (on-demand profile refresh)
  • /team/... endpoints
  • GET /credits/usage
  • POST /mcp

​
v2 behavior during the transition window

While both versions are operational:
v2 search may return IDs that can’t be fetched in v2. v2 search is wired to the new OpenSearch instance, while v2 fetch continues to read from the legacy Postgres database. Some IDs returned by v2 search will therefore 404 in v2 fetch. The recommended fix is to migrate fully to v3.
  • v2 fetch endpoints read from the legacy Postgres database.
  • v2 search endpoints are wired to the new OpenSearch instance.
  • v2 additional fields (tags, lists, etc.) are not maintained during the transition window. Use v3 if you need fresh tag/list data.

​
Removed fields (v3 Fetch Profile)

​
New fields in v3

The following fields are added to profile responses. See Models > Profile for details.

​
OpenSearch index changes (v3)

Beyond Fetch Profile responses, the OpenSearch profile index used by Search Profiles and Relationships has changed. See OpenSearch Profile Mappings (v3) for the full mapping.

​
Schema deltas since the initial v3 preview

If you integrated against an earlier v3 preview spec, the following deltas apply in the current release: Profile
  • profile_info.current_seniority renamed to current_seniorities (array). Same for experience[].seniority → seniorities. Update any query and response parsing.
  • New profile location fields: profile_info.location_locality, location_region, location_country, location_continent.
  • profile_info.social_media[] now includes entity_id, connections, followers, and join_date.
  • Removed: profile_info.linkedin_experience_count, profile_info.linkedin_education_count, profile_info.investor_data.
  • experience[].status is now required.
  • experience[].company.locations[].headquarter renamed to is_primary.
Company
  • company_info.workforce is a single object (was an array). Read workforce.headcount directly instead of workforce[0].headcount.
  • Investor-related fields (type, specialities, investments, geography_focus) moved into a nested company_info.investor object.
  • company_info.industry, website, data_updated_at, and size.class are no longer returned. Use the existing industries[], websites[], and updated_at.
  • crunchbase_id removed from funding investor entries — use crunchbase_slug.
  • Funding amount fields are now number (decimals allowed) instead of integer.
  • company_info.name is now required.
Endpoints
  • POST /v3/profiles/fetch and POST /v3/companies/fetch accept at most 1,000 entries per identifier array.
  • POST /v3/profiles/search and POST /v3/companies/search require from >= 0.
  • All /v3/* endpoints can return 402 Payment Required when the team’s API credit allowance is exceeded — handle it the same way you handle 429.

​
Field naming (v3 uses snake_case)

v3 endpoints standardize all field names to snake_case. v2 endpoints continue to use the original camelCase names until they are deprecated on July 15, EOD UTC. The Relationships, Network Mapper, and on-demand endpoints were already snake_case and are unchanged.

​
Authentication, errors, rate limits

Unchanged from v2:
  • Continue sending your API key in the x-api-key header.
  • Error response shapes are unchanged.
  • Rate limits, pagination tokens, and page size (1000) are unchanged.
  • Usage continues to be reported under GET /credits/usage.

​
Pricing changes

​
Migration checklist

  1. Update endpoint base paths from /v2/... and /companies/... to /v3/... for the 8 endpoints listed above.
  2. Stop requesting the connections and notes fields from Fetch Profile. Move connection lookups to the Relationships endpoint.
  3. Replace /v2/profiles/network-mapper with /v3/relationships, and /v2/network-mapper/partner/network with /v3/network-mapper (partner only).
  4. Test your integration end-to-end against v3 before July 15.
  5. Start consuming the new hiring, open_to_work, start_date_confidence, current_company_logo_url, and experience[].company.logo_url fields if relevant to your use case.

​
Need help?

Reach out to support@theswarm.com for migration questions.