Migrating v1 to v2

What changed in v2, what breaks, and a checklist to move your integration before v1 is retired.

Applies to

v1 + v2

→

Changed in v2

Code written for v1 needs a small update for this topic. The migration guide shows each change side by side.

Open the migration guide

v1 → v2

1# v1 (retired)
2curl "https://api.fernway.example/v1/sms/send?api_key=$KEY" \
3  -d to=+15555550123 -d text="Hi"
4 
5# v2
6curl https://api.fernway.example/v2/messages \
7  -H "Authorization: Bearer $KEY" \
8  -d '{"to":"+15555550123","channel":"sms","body":"Hi"}'

What changed

v2 merges the separate SMS, email and push endpoints into one Messages resource with a channel field. It also moves authentication to the Authorization header and replaces page numbers with cursors.

Breaking changes

/v1/sms/send, /v1/email/send and /v1/push/send are replaced by POST /v2/messages.
The text field is renamed to body.
api_key query parameters are no longer accepted.
page and per_page are replaced by cursor and limit.

Checklist

Upgrade to a 2.x SDK, update webhook handlers for the new event names, run your test suite against a test key, then switch live traffic. The retirement date in this template is a placeholder: set your own.

Placeholder API

Fernway is a fictional product used to show how this template works. Replace these docs with your own in the CMS.

← Webhook signatures

Going to production →