Versioning and deprecation
The version is in the path, /v1. Within v1 the API changes only in ways that keep working code working. A change that would break code comes as a new version, /v2.
What can change within v1
- New endpoints.
- New optional request fields.
- New response fields.
- New error codes.
- New values in enumerations such as
sourceandchannel, and new webhook event types.
A message's status never gains a value within v1.
What needs a new version
Removing or renaming a field or an endpoint, changing a field's type or format, making an optional field required, changing what an endpoint does by default, and adding a message status.
Deprecation
We announce a deprecation at least six months before the endpoint is removed. Until then it keeps working, and its responses carry three headers:
Deprecation: trueSunset: Thu, 15 Apr 2027 00:00:00 GMTLink: <https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel="deprecation"Sunset is the date after which it may be removed, and Link points at its migration guide. Log these headers or alert on them, so a deprecation never surprises you. Deprecations are also in the changelog.
Current deprecations
| Endpoint | Use instead | Sunset |
|---|---|---|
POST /v1/messages | POST /v1/sms/messages | 15 April 2027 |
Read the migration guide.
Webhooks
Webhook payloads carry api_version: "v1" and follow the same rules.