Deprecations
When a field on the Bird API is renamed, the old name keeps working. A request that uses one comes back with a Deprecation response header telling you so.
The header
A response to a request that carried a deprecated field includes:
| Header | Value |
|---|---|
| Deprecation | The date the deprecation was announced, for example @1786579200 |
| Link | <https://bird.com/docs/api/deprecations>; rel="deprecation" |
The Deprecation value records when the old name became deprecated, following RFC 9745. It does not announce a removal date.
Responses to requests that use only current field names carry neither header, so the header's presence is the signal: if you never see it, nothing you send is deprecated.
No removal date
Bird does not send a Sunset header because no removal date is available yet. A superseded name is removed only after usage has stopped. Bird contacts any workspaces that still use it before removal.
Treat the Deprecation header as a prompt to migrate at your own pace. It does not start a removal countdown.
What a deprecated field still does
A superseded name behaves exactly as it did:
- It is still accepted on requests, and still writes the same value.
- It is still returned on responses, alongside the name that replaced it.
- The current name wins if you send both, so you can migrate one call site at a time without the old name overwriting the new one.
Deprecated names are omitted from this reference, and the official SDKs expose only the current names. Upgrading your SDK therefore moves requests to the current field name.
Migrating
- Watch for the Deprecation header on your responses.
- Find the request that produced it, and check this reference for the operation to see the current field names.
- Move to the current name. Send only the new name once you have.
Current deprecations
| Operation | Deprecated | Use instead |
|---|---|---|
| Contacts: create, update, and create-or-update in bulk | phone | phone_number |
| Verify: create, check, and next channel | email_address, inside to |
Responses carry the superseded name too: a contact still comes back with phone beside phone_number, and a verification's to object with email_address beside email. A client reading either old name keeps working.