---
title: "Subscribe"
method: POST
path: "/api/v1/alerts/subscribe"
tags: ["alerts"]
---

# Subscribe

`POST /api/v1/alerts/subscribe`

## Request

- Base URL: `https://api.billcommons.org`
- URL: `https://api.billcommons.org/api/v1/alerts/subscribe`
- Auth: none declared

Subscribe an email to a topic's change digest.

Idempotent on (email, kind, target). New and inactive rows enter the
mailbox-confirmation queue; active rows remain unchanged. Every accepted
request returns the same lifecycle shape so anonymous callers cannot use
the endpoint to test membership.

## Request body

- AlertSubscribeRequest
  - `email` string, required
  - `kind` string
  - `target` string, required
  - `jurisdiction` string, nullable: Narrow the digest to one jurisdiction, e.g. 'FL'. Omit for a national digest across all 50 states + DC.

## Response `201`

Successful Response

- AlertSubscribeResponse
  - `subscribed` boolean, required
  - `lifecycle` string
  - `kind` string, required
  - `target` string, required
  - `jurisdiction` string, nullable
  - `meta` object, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/billcommons/apis/bill-commons-api.md) · [All operations](https://skmtc.dev/billcommons/apis/bill-commons-api/llms.txt) · [OpenAPI document](https://skmtc.dev/billcommons/apis/bill-commons-api/revisions/bfb8cd50a317?raw)