preferences

Get a preference

Returns one preference: the key it is about, the current statement on it, and the statement's provenance. An ID that does not exist in the workspace returns 404, including after a delete, which removes the record its ID pointed at.

get/v1/preferences/{preference_id}

Request

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

Headers

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.

Response

Preference.

idstring required
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.

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.

sender_scopestring nullable required

The sender the statement is limited to, or null when it covers the whole channel. On SMS this is the originator the person replied to; on WhatsApp it identifies the business account that messaged them; on Apple Messages for Business it is the Apple business ID used for invitations. Email preferences are always channel-wide, so it is always null there.

topic_idstring nullable required

The topic the statement is limited to, or null when it covers every topic. Part of the key that identifies a statement, alongside sender_scope.

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' required

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.

effective_atstring date-time required

When the statement was made, as reported by whoever made it. This is what orders one key's statements: a write dated before this moment is refused rather than applied.

originstring required

How the statement was made. Statements the person made themselves (unsubscribe_link, unsubscribe_event, keyword, preference_page) carry more weight than ones asserted on their behalf (api_key, user, import): a person's own opt-out cannot be overridden or deleted through this API. New origins can be added over time, so a value outside this list can be returned.

sourcestring nullable

Free-form note on where the statement came from, as supplied when it was recorded: a form name, an import batch, a campaign. Null when none was given.

consented_atstring date-time nullable

When the person consented, as evidenced by whoever asserted the grant. Null on statements that carry no consent evidence, including every opt-out.

contact_idstring
created_atstring date-time required
updated_atstring date-time required

Example response

{
  "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 3 revisions of this API.