> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theswarm.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrating to v3
> Everything you need to migrate from v2 to v3 of The Swarm API — timeline, endpoint mapping, removed fields, and new fields.
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
| Milestone | Date |
| -------------- | -------------------- |
| v3 release | Live |
| 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`](/docs/endpoints/v3/search-profiles) | Same request/response schema |
| `POST /v2/profiles/fetch` | [`POST /v3/profiles/fetch`](/docs/endpoints/v3/fetch-profile) | `connections` and `notes` fields removed |
| `POST /companies/search` | [`POST /v3/companies/search`](/docs/endpoints/v3/search-companies) | Same request/response schema |
| `POST /companies/fetch` | [`POST /v3/companies/fetch`](/docs/endpoints/v3/fetch-company) | Same request/response schema |
| `POST /v2/profiles/network-mapper` | [`POST /v3/relationships`](/docs/endpoints/v3/relationships) | Renamed. **Free** to call. Synchronous response — no status endpoint. |
| `POST /v2/network-mapper/partner/network` | [`POST /v3/network-mapper`](/docs/endpoints/v3/network-mapper) | Partner permission required. 1 credit per non-empty response. |
| `GET /v2/network-mapper/partner/network/status` | [`GET /v3/network-mapper/status`](/docs/endpoints/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/...` 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)
| Field | What to do instead |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `connections` | Use the [Relationships](/docs/endpoints/v3/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](/docs/enrichment-data/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](/docs/endpoints/v3/search-profiles) OpenSearch index with a `nested` query scoped to your `team_connections.team_id`. See [Relationships endpoint examples](/docs/examples/relationships-endpoint#filtering-by-team-connection-origin). |
| `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](/docs/endpoints/v3/search-profiles) and [Relationships](/docs/endpoints/v3/relationships) has changed. See [OpenSearch Profile Mappings (v3)](/docs/enrichment-data/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 |
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`](/docs/api-reference/credits-usage).
### Pricing changes
| Endpoint | v2 cost | v3 cost |
| ---------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------- |
| Profile / Company search and fetch | Same as today | Same as today |
| [Relationships](/docs/endpoints/v3/relationships) (team network) | 1 credit per fetched profile | **Free** |
| [Network Mapper (Partner)](/docs/endpoints/v3/network-mapper) | Same as today | **1 credit per non-empty response**, partner permission required (403 otherwise) |
## 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](/docs/endpoints/v3/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](mailto:support@theswarm.com) for migration questions.