Record a preference
/v1/preferencesconst result = await bird.preferences.create({
channel: "sms",
handle: "+15550001234",
status: "revoked",
});
console.log(result.applied, result.preference?.id);result = client.preferences.create(
channel="email",
handle="jane@acme.com",
status="granted",
consented_at="2026-08-20T14:03:10Z",
source="signup-form-v2",
)
if result.applied and result.preference and result.preference.status == "granted":
print(result.preference.id)result, err := client.Preferences.Create(context.Background(), bird.PreferencesCreateParams{
Channel: bird.PreferenceChannelEmail,
Handle: "recipient@example.com",
Status: bird.PreferenceStatusGranted,
Source: "signup-form-v2",
ConsentedAt: time.Now(),
})
if err != nil {
log.Fatal(err)
}
// A surviving opt-out or deletion answers Applied false instead of an error.
if result.Applied != nil && *result.Applied && result.Preference != nil && result.Preference.Status != nil && *result.Preference.Status == bird.PreferenceStatusGranted {
fmt.Println("grant recorded")
}$result = $bird->preferences->create(
channel: 'email',
handle: 'jane@acme.com',
status: 'granted',
source: 'signup-form-v2',
consentedAt: new DateTimeImmutable('2026-08-20T14:03:10Z'),
);
$preference = $result->getPreference();
if ($result->getApplied() && $preference?->getStatus() === 'granted') {
echo 'grant recorded';
}bird preferences create \
--channel sms \
--coverage non_transactional \
--handle +15550001234 \
--status revokedcurl -X POST "https://us1.platform.bird.com/v1/preferences" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel": "sms",
"handle": "+15550001234",
"status": "revoked",
"coverage": "non_transactional"
}'{
"transition_id": "prt_01krdgeqcxet5s7t44vh8rt9mg",
"preference": {
"id": "prf_01krdgeqcxet5s7t44vh8rt9mg",
"channel": "sms",
"handle": "+15550001234",
"sender_scope": "+15557654321",
"topic_id": null,
"status": "revoked",
"coverage": "non_transactional",
"origin": "api_key",
"source": "signup-form-v2",
"contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
"brand_id": null,
"created_at": "2026-05-20T09:14:52Z",
"updated_at": "2026-05-25T16:42:01Z"
}
}
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, optional sender scope, and email Brand, 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. For an email Brand complaint, only this individual-recipient operation can record the newer consent that clears complaint protection. Bulk writes and imports cannot clear it. Bird accepts your assertion that the recipient has consented; optional source describes where consent came from, without verification. Other applicable opt-outs and workspace-wide delivery blocks still apply. Consent history can still be retained when a later ordinary opt-out or deletion remains in force. Such a grant returns applied: false with the surviving preference, or null after deletion.
A 201 means this key had no record and one was created; a 200 returns the key's surviving record, or preference: null when a later deletion remains in force. The result distinguishes an effective preference write, repeat, or refusal.
Verzoekpayload
handleWho 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.
channelThe 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.
Possible values (may grow over time): email, sms, whatsapp, amb
statusWhat 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.
Possible values: granted, revoked
coverageHow much traffic the statement covers. Defaults to non_transactional, which keeps transactional messages such as receipts and verification codes flowing. Apple Messages for Business phone invitations have no transactional exemption, so either value covers them.
Possible values: all, non_transactional
sender_scopeLimit 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 belong to the selected Brand.
sourceFree-form note on where the statement came from: a form name, an import batch, a campaign. For a grant, it can describe how you collected consent. Stored verbatim and returned on the preference; Bird does not verify this note. It does not grant permission to clear a complaint.
consented_atWhen 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.
brand_idBrand selection is in preview. Select the business for an email preference. Omitted or null selects the original business. Unsupported on other channels. An additional Brand supports non_transactional coverage only. Explicit selection returns 422 when unavailable. Existing opt-outs can be recorded for archived Brands; grants to archived Brands return 422. Consent grants for active additional Brands return 422 when unavailable. A Brand not found in this workspace returns 404.
Response Payload
appliedWhether the request took effect. False when causal ordering or protected complaint rules refuse the request; the surviving statement is returned in preference. A grant returns false when a newer opt-out or deletion survives, even if its consent history is retained.
transition_idIdentifies this write on the key's record, for applied and refused requests alike. Null when the write was a repeat of the current statement and recorded nothing new.
preferenceThe key's surviving statement. Null after an applied delete, when the key is back to having no record. It is also null after a refused grant when a later deletion remains in force.
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.