Sunset header with that date.
What stays the same
- Tokens. Your API token works on both versions.
- Rate limits. 300 requests a minute, 10,000 an hour and 100,000 a day per team, shared between v1 and v2.
- Plans. Lists and campaigns need an outreach-enabled plan. Messaging someone who isn’t a contact yet needs the Advanced API add-on.
- Webhook delivery. The same signature header, and the same 7-day replay window.
Start here
Five v1 endpoints have no v2 endpoint of the same shape. Most integrations use at least one.Quick send
POST /threads/messages becomes POST /messages with a profile target.
{ message, thread }. Store thread.id: a later send can use { "type": "thread", "threadId": "…" }.
platform is required and must be the account link’s platform. If you have an Inboxapp contact ID instead of a platform ID, use { "type": "contact", "accountLinkId": "…", "contactId": "…" }.
Lookup by username
GET /threads/lookup-by-username becomes two calls: find the contact, then its threads.
username without its @.
Reactions
The doubled path segment is gone, and the thread ID leaves the path.
Both return the message’s
reactions instead of { success, messageId }.
Create thread
POST /threads is removed. A thread appears when its first message is sent, and POST /messages returns it.
The /campaigns/v2 alias
Removed. See Lists and campaigns.
What changes everywhere
Pagination
paginate.ts
Errors
Endpoint map
Team, members, account links
Threads
Thread filters
Thread fields
Messages
Message fields
Prospects become contacts and profiles
v1’s prospect splits in two:- A profile is the person’s account on one platform:
username,handle,displayName,avatarUrl,bio, follower counts, andplatformData. - A contact is your team’s record of the person:
statusId,tagIds,notes,valuation,assigneeId, and theirprofiles.
Reads never create a contact: a person your team has never talked to or imported has none. Message them with a
profile target.
Profile fields
Tags, statuses, colors
Lists and campaigns
In v2, lists, leads, import jobs and campaigns are available to outreach-enabled plans only. On such a plan, their endpoints are listed in the API explorer in your team’s settings, and they keep their v1 request and response shapes. They can change or be removed within v2, and their errors use the v2 body.Webhooks and events
A subscription receives one version. New subscriptions receive v2. To switch an existing one, open it in Settings → Webhooks and select Move to v2. You can’t move back to v1. v2 events are thin. They name the object that changed and carry only the values of the change. Readobject.url for the current state.
Sequence numbers are shared by both versions and by webhooks. To backfill after downtime, call
GET /events?afterSeq=… with the seq of the last event you processed.
Signatures are unchanged: see Verifying webhook signatures.
Send safely
POST /messages takes an Idempotency-Key header. A retry with the same key and body returns the original result with 200 instead of sending twice.
send.ts
Checklist
- Change the base URL to
/api/v2 - Read collections from
dataand page withnextCursor - Replace bracket query parameters with repeated keys
- Branch on error
code - Replace prospect IDs with contact IDs, and
prospectfields withprofileandcontact - Send through
POST /messageswith anIdempotency-Key - Move lists and campaigns to their v2 endpoints, on an outreach-enabled plan
- Switch webhook subscriptions to v2 and read
object.urlfor state