Sign inGet Started

Delete a preference

DELETE
/v1/preferences/{preference_id}
const result = await bird.preferences.delete("prf_01krdgeqcxet5s7t44vh8rt9mg");
if (!result.applied) {
  console.log("refused — a newer statement survived:", result.preference?.status);
}
Reactie200
{
  "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"
  }
}

Deletes a preference, returning its key to having no record, as if nothing had ever been stated. The deletion itself is kept on the key's history, so a later statement is still ordered against what was deleted.

Person-stated opt-outs and active email Brand complaints cannot be deleted. Attempts return 422 E25005. To record renewed consent, use the individual POST /v1/preferences operation with status: granted and consented_at strictly later than the opt-out or complaint. Bulk writes and imports cannot clear complaints. Other applicable opt-outs and delivery blocks still apply.

A delete is ordered like any statement, using the time it is received: if the record carries a statement made after that moment, the delete is refused and returned with applied: false alongside the surviving record. An ID that does not exist in the workspace returns 404.

Parameters

preference_idstring

ID of the preference, as returned when it was recorded or listed. The ID stays stable while the key holds a record; deleting and re-recording the same key mints a new one.

Response Payload

applied
boolean
verplicht

Whether 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_id
nullable string
verplicht

Identifies 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.

preference
nullable object
verplicht

The 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.

Onderliggende attributen tonen

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.