# Get a preference

`GET /v1/preferences/{preference_id}`

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.

## Code samples

### TypeScript

```ts
const preference = await bird.preferences.get(
  "prf_01krdgeqcxet5s7t44vh8rt9mg",
);
console.log(preference.status, preference.coverage);
```

### Python

```py
preference = client.preferences.get("prf_01krdgeqcxet5s7t44vh8rt9mg")
print(preference.status, preference.coverage)
```

### Go

```go
pref, err := client.Preferences.Get(context.Background(), "prf_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
	log.Fatal(err)
}
fmt.Println(*pref.Status, *pref.Coverage)
```

### PHP

```php
$preference = $bird->preferences->get('prf_01krdgeqcxet5s7t44vh8rt9mg');
echo $preference->getChannel(), ' ', $preference->getStatus();
```

### CLI

```sh
bird preferences get <preference-id>
```

### cURL

```sh
curl -X GET "https://us1.platform.bird.com/v1/preferences/{preference_id}" \
  -H "Authorization: Bearer $TOKEN"
```

## Example response `200`

```json
{
  "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",
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z"
}
```

## Path parameters

- `preference_id` (string): 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 body

- `id` (string, required)
- `channel` (string, required)
- `handle` (string, required): Who the statement is about: an email address on the email channel, a phone number in E.164 format on SMS and WhatsApp.
- `sender_scope` (nullable string, 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. Email preferences are always channel-wide, so it is always null there.
- `topic_id` (nullable string, 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` (string, required)
- `coverage` (string, required)
- `effective_at` (string, 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.
- `origin` (string, required)
- `source` (nullable string): 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_at` (nullable string): When the person consented, as evidenced by whoever asserted the grant. Null on statements that carry no consent evidence, including every opt-out.
- `contact_id` (nullable string): The contact whose handle matched when the statement was recorded. Null when no contact matched at that moment; it is not updated when contacts change later.
- `created_at` (string, required)
- `updated_at` (string, required)