Deprecations
Bird deprecates three different things, and they behave differently. A request field is renamed, and the old name keeps working alongside the new one. A query parameter is superseded by a better filter, and it keeps working unchanged. A request body shape is superseded by a new shape, and the old shape keeps being accepted. In every case, 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, parameter, or body shape 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 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 affected customers before removal.
Treat the Deprecation header as a prompt to migrate at your own pace. It does not start a removal countdown.
A renamed request field
A superseded field 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.
Renamed field 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.
A deprecated query parameter
A query parameter is deprecated when a better filter replaces it. It behaves differently from a renamed field in three ways worth knowing:
- It stays published everywhere. Removing it from the reference and the SDKs would break callers who already send it, so it keeps its row on this reference, its field on every SDK, its flag on the CLI, and its entry in the MCP tool schema. Upgrading your SDK does not migrate you.
- There is no response half. A query parameter only ever appears on the request, so nothing in the response body changes and there is no new name to read back.
- The replacement may not be one parameter. A filter is sometimes superseded by a pair, so the parameter's own description names what to use instead rather than pointing at a single successor.
Because upgrading does not move you, the Deprecation header is the only signal you will get. Check the parameter's description in this reference: a deprecated one opens with Deprecated: and names its replacement.
A superseded request body shape
The batch send endpoints, POST /v1/sms/batches and POST /v1/email/batches, once took the batch as a bare top-level JSON array. They now take an object whose messages array holds the same items, which is the shape this reference documents. A request whose body is still the bare array keeps working exactly as before, and comes back with the Deprecation header. The official SDKs send the messages object, so upgrading your SDK moves your requests to the current shape.
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 names and request shape.
- Move to the current name or shape. Send only the current form once you have.
Current deprecations
| Operation | Deprecated | Use instead |
|---|---|---|
| Contacts: create, update, and create-or-update in bulk | phone field | phone_number |
| Verify: create, check, and next channel | email_address field, inside to | |
| WhatsApp: list messages | phone_number query parameter | to or from |
| SMS and email: create a batch of messages | bare-array request body | an object with messages |
The two field renames also return the superseded name: 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.
to and from on the WhatsApp message list each match one end of the message, and each accepts a phone number or a business-scoped user ID. phone_number matched the contact in either direction, so a search that does not care about direction needs both filters, one request each.