v3 is coming soon. The endpoints and schemas described on this page are documented here for reference and integration planning. They are not yet live in production — exact launch date will be announced shortly.
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
| Milestone | Date |
|---|
| v3 release | Coming soon |
| v2 deprecation | July 15, EOD UTC |
Endpoint mapping
Only 8 endpoints move to v3. Everything else stays on its current path.
| v2 endpoint | v3 endpoint | Notes |
|---|
POST /v2/profiles/search | POST /v3/profiles/search | Same request/response schema |
POST /v2/profiles/fetch | POST /v3/profiles/fetch | connections and notes fields removed |
POST /companies/search | POST /v3/companies/search | Same request/response schema |
POST /companies/fetch | POST /v3/companies/fetch | Same request/response schema |
POST /v2/profiles/network-mapper | POST /v3/relationships | Renamed. Free to call. Synchronous response — no status endpoint. |
POST /v2/network-mapper/partner/network | POST /v3/network-mapper | Partner permission required. 1 credit per non-empty response. |
GET /v2/network-mapper/partner/network/status | GET /v3/network-mapper/status | Partner permission required |
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/... endpointsGET /credits/usagePOST /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)
| Field | What to do instead |
|---|
connections | Use the Relationships endpoint. It exposes connection data and is free to call. |
notes | The notes feature is being retired. There is no v3 replacement. |
New fields in v3
The following fields are added to profile responses. See Models > Profile for details.
| Field | Type | Description |
|---|
profile_info.hiring | boolean | Signals that the profile is actively hiring. |
profile_info.open_to_work | boolean | Signals that the profile is open to new opportunities. |
profile_info.experience[].start_date_confidence | string ("validated" or "low") | Confidence indicator on each experience entry’s start date. |
profile_info.current_company_logo_url | string (CDN URL) | Logo URL for the profile’s current company. |
profile_info.experience[].company.logo_url | string (CDN URL) | Logo URL on each experience entry’s company. |
team_connections.origins | keyword (nested) | Provenance of each team connection. Searchable via the v3 Search Profiles OpenSearch index with a nested query scoped to your team_connections.team_id. See Relationships endpoint examples. |
connections.origins | keyword (nested) | Same origins concept on the connections array. Query-side counterpart of the response-side connections[].sources[].origin enum. |
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.
| v2 (camelCase) | v3 (snake_case) | Where |
|---|
paginationToken | pagination_token | Search request and response |
totalCount | total_count | Search response |
inNetworkOnly | in_network_only | Search Profiles request |
linkedinNames | linkedin_names | Fetch Profile / Fetch Company request, and results[].found_by |
linkedinIds | linkedin_ids | Fetch Profile / Fetch Company request, and results[].found_by |
linkedinEntityIds | linkedin_entity_ids | Fetch Profile request, and results[].found_by |
notFound | not_found | Fetch Profile / Fetch Company response |
company_info.Size | company_info.size | Fetch Company response |
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
| Endpoint | v2 cost | v3 cost |
|---|
| Profile / Company search and fetch | Same as today | Same as today |
| Relationships (team network) | 1 credit per fetched profile | Free |
| Network Mapper (Partner) | Same as today | 1 credit per non-empty response, partner permission required (403 otherwise) |
Migration checklist
- Update endpoint base paths from
/v2/... and /companies/... to /v3/... for the 8 endpoints listed above.
- Stop requesting the
connections and notes fields from Fetch Profile. Move connection lookups to the Relationships endpoint.
- Replace
/v2/profiles/network-mapper with /v3/relationships, and /v2/network-mapper/partner/network with /v3/network-mapper (partner only).
- Test your integration end-to-end against v3 before July 15.
- 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.
