preferences

Record a preference

Records one statement, a grant or an opt-out, for a handle on one channel. Writing is an upsert: the key is the channel, handle, and optional sender scope, and a new statement replaces the key's current one.

Statements are ordered by when they were made, not when they arrive. A statement older than the key's current one is refused and returned with applied: false alongside the statement that survived; refusals are recorded on the key's history. Granting over a stored opt-out needs consented_at later than the opt-out, and a person's own opt-out (an unsubscribe, a stop keyword) cannot be overridden by a grant asserted on their behalf.

A 201 means this key had no record and one was created; a 200 returns the key's surviving record, whether this statement replaced it, repeated it, or was refused.

post/v1/preferences

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/preferences
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

handlestring required

Who the statement is about: an email address on the email channel, a phone number in E.164 format on SMS, WhatsApp, and Apple Messages for Business.

channelstring required

The channel a preference statement applies to. A preference addresses one channel: the handle that identifies the person differs per channel, so opting out of one channel says nothing about the others. New channels can be added over time, so a value outside this list can be returned.

status'granted' | 'revoked' required

What the statement says: granted records consent to receive messages, revoked records an opt-out. There is no third state: a person who never stated anything simply has no preference on record.

coverage'all' | 'non_transactional'

How much traffic the statement covers. non_transactional covers marketing and other non-essential messages while transactional messages such as receipts and verification codes keep flowing; all covers every message including transactional ones. Apple Messages for Business phone invitations have no transactional exemption, so either value covers them.

sender_scopestring

Limit the statement to one sender instead of the whole channel. On SMS this is the originator; on WhatsApp it identifies the business account; on Apple Messages for Business it is the Apple business ID used for invitations. Not supported on email, where preferences are always channel-wide.

sourcestring

Free-form note on where the statement came from: a form name, an import batch, a campaign. Stored verbatim and returned on the preference.

consented_atstring date-time

When the person consented, on a granted statement. Required evidence when granting over a stored opt-out: the grant applies only if this is later than the opt-out it reverses. May not be in the future.

Example request

{
  "handle": "+15550001234",
  "channel": "sms",
  "status": "revoked",
  "coverage": "non_transactional",
  "sender_scope": "+15557654321",
  "source": "signup-form-v2"
}

Response

The key already had a record. The result says whether this statement replaced it, repeated it, or was refused as out of order.

appliedboolean required

Whether the request took effect. False only when it was refused as out of order; the surviving, newer statement is returned in preference.

transition_idstring required

Example response

{
  "transition_id": "prt_01krdgeqcxet5s7t44vh8rt9mg",
  "preference": {
    "id": "prf_01krdgeqcxet5s7t44vh8rt9mg",
    "channel": "sms",
    "handle": "+15550001234",
    "sender_scope": "+15557654321",
    "status": "revoked",
    "coverage": "non_transactional",
    "origin": "api_key",
    "source": "signup-form-v2",
    "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
    "created_at": "2026-05-20T09:14:52Z",
    "updated_at": "2026-05-25T16:42:01Z"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.