> ## Documentation Index
> Fetch the complete documentation index at: https://developers.explorium.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from v1 to v2

> How to move an existing AgentSource v1 integration to v2, including endpoint mapping, breaking changes, and the v1 deprecation timeline.

## There is no hard cutover

v2 ships alongside v1. v1 keeps running in parallel and is wound down in stages, so you have a full migration window and can move at your own pace.

<Tip>
  **Prefer to automate it?** The [v1 → v2 upgrade skill](/v2/upgrade-skill) applies this whole guide for you: install it in Claude Code (or any Agent Skills–compatible agent) and it audits your codebase, rewrites endpoints, fields, and filters, updates your tests, and reports what needs human review.
</Tip>

## v1 deprecation timeline

<Warning>
  v2 reached general availability on **September 2, 2026** — that date is T0 below. Later milestones are **indicative** and subject to minor change.
</Warning>

| Stage                     | Timing               | What happens                                                                                                                                     |
| :------------------------ | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Parallel availability** | At v2 GA (T0)        | v2 and v1 run side by side. v1 is marked deprecated, with deprecation / sunset signaling, but stays fully functional.                            |
| **v1 end of support**     | \~6 months after T0  | v1 is no longer actively supported — no new fixes, signals, or SLA. Endpoints still respond, but all customers should be migrated by this point. |
| **v1 retirement**         | \~12 months after T0 | v1 is fully sunset and decommissioned; v1 endpoints no longer serve traffic.                                                                     |

## Migration steps

<Steps>
  <Step title="Move to /v2 paths">
    Replace the `/v1` prefix with `/v2` on every endpoint. See the [mapping](#endpoint-mapping) below.
  </Step>

  <Step title="Collapse bulk calls into single endpoints">
    Drop the `/bulk_enrich` suffix. The single endpoint accepts one ID or a list of IDs, so a bulk call becomes the same endpoint with a list payload.
  </Step>

  <Step title="Pick sync or async">
    Use `.../enrich` for immediate results, or `.../job` for large runs. Async is capped at 10K input records and 24 hours per job.
  </Step>

  <Step title="Update renamed paths and fields">
    Rename `contacts_information` to `contact_information`, and update the corrected [signal field names](/v2/whats-new#signal-fixes).
  </Step>

  <Step title="Handle removed response fields">
    Stop reading `entity_id`, `display_name` on business LinkedIn posts, and the address signals on `company_ratings_by_employees`.
  </Step>

  <Step title="Replace contact-availability filters">
    `has_email` and `has_phone_number` are removed from prospects fetch and stats. Use `has_contact_details` — `email`, `phone`, or `email_and_phone` to reproduce the old behavior, or `email_or_phone` for at-least-one. See [Removed filters](/v2/whats-new#removed-filters).
  </Step>

  <Step title="Check changed fetch defaults">
    Remove the `size` pagination parameter, and set `include_operating_locations` explicitly if you relied on the old default.
  </Step>
</Steps>

## Endpoint mapping

| v1                                                               | v2                                                                                      | Notes                                                                                                        |
| :--------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| `/v1/businesses/{enrichment}/bulk_enrich`                        | `/v2/businesses/{enrichment}/enrich`<br />`/v2/businesses/{enrichment}/job`             | Bulk route removed; pick sync or async                                                                       |
| `/v1/prospects/contacts_information/bulk_enrich`                 | `/v2/prospects/contact_information/enrich`<br />`/v2/prospects/contact_information/job` | Also renamed                                                                                                 |
| `/v1/businesses/research/bulk_enrich`                            | `/v2/businesses/research/enrich`<br />`/v2/businesses/research/job`                     | Bulk route removed; pick sync or async                                                                       |
| `/v1/prospects/research/bulk_enrich`                             | `/v2/prospects/research/enrich`<br />`/v2/prospects/research/job`                       | Bulk route removed; pick sync or async                                                                       |
| Business / prospect autocomplete routes                          | `/v2/autocomplete`                                                                      | Consolidated into one endpoint                                                                               |
| `/v1/businesses/match`, `/v1/businesses`, `/v1/businesses/stats` | `/v2/...` equivalents                                                                   | Path change only                                                                                             |
| `/v1/prospects/match`, `/v1/prospects`, `/v1/prospects/stats`    | `/v2/...` equivalents                                                                   | Path change only                                                                                             |
| Credits                                                          | `/v2/...` equivalents                                                                   | Path change only                                                                                             |
| `/v1/webhooks` (single, partner-level)                           | [`/v2/webhooks`](/v2/endpoints/webhooks) — multiple, tenant-scoped, by `webhook_id`     | Not a path rename: register per destination, store each secret; the legacy webhook appears as `legacy: true` |
| `/v1/{entity}/events/enrollments`                                | `/v2/{entity}/events/enrollments`                                                       | v2 enrollments require a `webhook_id` binding                                                                |
| `/v1/{entity}/events`                                            | [`/v2/{entity}/events`](/v2/endpoints/events)                                           | Path change; `new_funding_round` payloads use the corrected `funding_*` field names                          |

## Breaking changes checklist

* [ ] `/v2` path prefix applied everywhere
* [ ] `/bulk_enrich` calls collapsed into `/enrich` or `/job`
* [ ] `contacts_information` renamed to `contact_information`
* [ ] `founding_stage` → `funding_stage`, `founding_date` → `funding_date`
* [ ] `professions_email` → `professional_email`
* [ ] `money_spend_on_website_technologies` → `money_spent_on_website_technologies` (webstack)
* [ ] `latest_funding_increase_in_percents` → `latest_funding_increase_percentage` (funding\_and\_acquisition)
* [ ] `time_took_in_seconds` → `time_taken_in_seconds` (`response_context`, every endpoint)
* [ ] `entity_id` no longer read
* [ ] `display_name` no longer read from business LinkedIn posts
* [ ] Address signals no longer read from `company_ratings_by_employees`
* [ ] `has_email` / `has_phone_number` replaced with `has_contact_details`
* [ ] `size` pagination parameter removed
* [ ] `include_operating_locations` set explicitly
* [ ] Async payloads within the 10K record limit
* [ ] Autocomplete calls pointed at `/v2/autocomplete`
* [ ] Stop reading `emails` from contact responses — use `professional_email`
* [ ] `employee_joined_company` → `executive_joined_company` in event filters, enrollments, and payload handling

## Related

<Columns cols={2}>
  <Card title="What's new" icon="sparkles" href="/v2/whats-new">
    The full change list
  </Card>

  <Card title="Conventions" icon="list-check" href="/v2/conventions">
    Rules that apply across every v2 endpoint
  </Card>
</Columns>