What Does Instantly.ai API V2 Add Over V1?

Instantly.ai API V2 roughly doubles the number of available endpoints compared to V1 and introduces API Scopes, a permission system that lets you issue API keys with specific read or write access rather than full account control. Both changes are live now for Instantly users.

What Changed Between V1 and V2

V1 offered a limited set of endpoints covering campaign management and lead operations. V2 expands that significantly. You can now interact programmatically with accounts, analytics, background jobs, email verification, and more granular campaign controls that V1 simply did not expose.

The other major addition is API Scopes. When you create an API key in V2, you assign it specific permissions from a defined list rather than handing out a key that can do everything your account can do. A key for a reporting dashboard gets read-only analytics access. A key for a Clay pipeline gets lead write permissions and nothing else.

The auth method also shifts. V1 used a query-parameter approach for passing keys in many requests. V2 moves authentication to the Authorization header with a Bearer token pattern, which is standard and easier to handle in most HTTP clients and integration platforms.

Why Scoped API Keys Matter

If a V1 API key leaked or was compromised, an attacker had access to everything: campaigns, leads, sending accounts. The blast radius was the full account. Scoped keys change that calculation.

Say you share access with a client who wants to pull reporting data. You create a key scoped to read-only analytics. If they inadvertently expose it in a spreadsheet or a browser request, whoever finds it cannot touch campaigns or leads. The exposure is contained.

Same logic applies to internal tools. An inbox monitoring script does not need campaign write access. A webhook receiver that adds leads to a campaign does not need account-level permissions. Scope keys to the minimum they need, and operational mistakes or security incidents stay contained.

For agencies running multiple client accounts, this also creates a cleaner permission model. You can give clients visibility into their own reporting without handing them the keys to your sending infrastructure.

New Automation Use Cases

The endpoint expansion opens pipelines that were awkward or impossible to build cleanly in V1.

CRM sync: V2 exposes more lead and contact data points programmatically. You can build two-way sync with a CRM without relying on Zapier or webhooks as the only path. Pull reply status, update lead fields, push back to your CRM on a schedule.

Clay and webhook pipelines: Clay operators building enrichment-to-campaign flows can now push leads directly into specific campaigns via API with more control over how those leads are staged. The tighter auth model also makes it easier to handle Clay webhooks securely: create a scoped key that only allows lead writes, drop it into Clay, and you have reduced the exposure if that key appears in a Clay table someone shares.

Multi-seat agency workflows: With scoped keys, you can build internal tooling where different team members or client-facing dashboards hit the API with appropriate permissions. A client portal that reads campaign performance does not need the same key your ops team uses to manage sending accounts.

Background job monitoring: V2 includes endpoints for background job status. If you trigger bulk operations programmatically, you can now poll for completion rather than guessing or waiting on UI state.

How to Migrate from V1 to V2

A few things to check before switching:

Auth header change. V1 requests passing the API key as a query parameter will not work in V2. Update your HTTP client configuration to send Authorization: Bearer YOUR_KEY in the request headers. This is a required change, not optional.

Endpoint paths. Some endpoints changed paths or request body structure between versions. Review the V2 documentation against each endpoint you currently call. Do not assume a V1 endpoint maps cleanly to V2 without checking.

Generate new keys. V1 keys do not carry over scopes. You will need to generate new V2 keys and assign scopes during creation. Plan this around your current integration uptime, particularly if you have production workflows running against V1.

Test in a non-production campaign first. Run your updated integration against a test campaign before pointing it at active sequences. The endpoint and auth changes are enough that integration errors will surface quickly on the first few requests.

V1 is not being removed immediately, so you have time to migrate deliberately rather than under pressure. But any new integrations should be built on V2 from the start.

Who Should Prioritize Upgrading Now

Upgrade now if:

• You are building a new integration. There is no reason to build on V1 at this point.
• You share API keys with clients or external tools. Scoped keys reduce risk in exactly those scenarios.
• You are running a Clay pipeline that writes leads to Instantly. The tighter auth model and expanded endpoints both help here.

You can wait if:

• Your current V1 integration is stable, low-traffic, and not client-facing. V1 still works. Migrating a working integration has a cost, and if you are not using any new V2 features, there is no urgency.
• You do not have the engineering time right now to test the auth and endpoint changes carefully. A hasty migration that breaks a production sequence is worse than staying on V1 temporarily.

The practical upside of V2 is that it treats the API like a real integration surface rather than an afterthought. Scoped keys and doubled endpoints are not features most Instantly users will think about. For operators building custom workflows or running agency setups, they change what you can safely automate and how tightly you can control access.