SMS v1 and migration
V1 remains available
Section titled “V1 remains available”Historical /api/smsko/v1/ routes, keys and responses are preserved during migration.
The historical documentation and v1 Postman collection describe that legacy contract.
This page does not announce a retirement date. The schedule depends on v2 general availability, coverage of existing use cases and support for integrators.
Compare the contracts
Section titled “Compare the contracts”Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.
| Topic | v1 | v2 |
|---|---|---|
| Namespace | /api/smsko/v1/ | /api/sms/v2/ |
| Key | Historical contract | Organization bf_sms_ key only |
| Authentication | Authorization: <key> with the raw key, without a Bearer prefix | Authorization: Bearer <key> |
| Organization | Historical resolution | Derived from the key |
| Sending | Historical routes | messages resource |
| Scheduling | Dedicated routes | send_at field or message-batches resource |
| Timestamp | Historical format | RFC 3339 with an explicit timezone |
| Idempotency | Historical behavior | Required key for messages and batches |
| Status | Historical contract | UUID identifier and explicit state |
| Responses | Historical responses | English fields, codes and messages |
V2 rejects a historical key even if it has been associated with an organization. Do not simply replace v1 with v2 in a URL.
In v1, the header directly contains the historical or organization key accepted by that contract. V2 requires both the Bearer prefix and an organization key.
Map each use case
Section titled “Map each use case”The v1 paths below use the /api/smsko/v1/ base; v2 paths use /api/sms/v2/.
Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.
| Use case | V1 route | V2 equivalent |
|---|---|---|
| Immediate send | POST send/ | POST messages/, without send_at |
| Single schedule | POST sendlater/ | POST messages/, with send_at |
| Multiple schedules | POST sendbulk/ | POST message-batches/, with one shared future send_at |
| Balance | GET balance/ | GET balance/ |
| Contact | POST contact/ | POST contacts/ |
| Delivery status | GET get-delivery-status/ | GET messages/{message_id}/ |
This mapping describes how use cases migrate; request bodies and responses are not interchangeable. Refer to the historical documentation and collection linked above for complete v1 fields and responses.
Migrate gradually
Section titled “Migrate gradually”- Inventory immediate sends, schedules, batches, balance reads, contacts and status checks.
- Create an organization key with the permissions you need.
- Update request fields and response handling.
- Store idempotency data and public identifiers in your application.
- Verify errors, insufficient credits and unknown outcomes.
- Move each business operation to one contract at a time.
Avoid submitting the same business operation to v1 and v2 in parallel: v2 idempotency does not automatically deduplicate a v1 submission. Continue tracking messages created in v1 through their historical contract.
The Postman collection linked above remains Legacy v1. The SMS v2.0.1 Postman collection covers all seven operations of the production v2 contract. Read the v2 reference to prepare your private key, variables and retries with the same idempotency key. Postman requests run manually against production.