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, e.g. @1786579200 |
| Link | <https://bird.com/docs/api/deprecations>; rel="deprecation" |
The Deprecation value is a timestamp of the announcement, not of removal. It tells you when the old name became deprecated, following RFC 9745.
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
We do not send a Sunset header, because that would publish a removal date we cannot yet stand behind. A superseded name is removed only once we can see that nobody is still sending it, and we contact the workspaces that are still sending it before removing anything.
Treat the Deprecation header as the prompt to migrate at your own pace, not as a 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 not listed in this reference, and the official SDKs never expose them: an SDK only ever carries the current name. So upgrading your SDK moves you off the old name on its own, and the field simply becomes the new one.
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 |
Contacts responses also still carry phone alongside phone_number, so a client reading the old name keeps working.