---
title: "Create a pending StreetProof alert subscription"
method: POST
path: "/api/v1/alerts/subscribe"
---

# Create a pending StreetProof alert subscription

`POST /api/v1/alerts/subscribe`

## Request

- Base URL: `https://streetproof.com`
- URL: `https://streetproof.com/api/v1/alerts/subscribe`
- Auth: none required

Creates or updates a pending alert subscription for StreetPulse-derived city, industry, or entity events. Matching events are queued, but external email/webhook delivery waits for verification, SMTP and partner controls.

## Request body

- AlertSubscribeRequest
  - `email` string, email, required
  - `city` string, required: City slug, e.g. calgary
  - `channel` 'email' | 'dashboard' | 'webhook'
  - `entity_public_id` string: Restrict alerts to one entity
  - `industry_code` string: Restrict city alerts to one industry
  - `event_types` string[]
  - `min_confidence` number
  - `webhook_url` string, uri: Required only when channel=webhook.

## Response `200`

Existing subscription updated

- AlertSubscriptionResponse
  - `schema` 'com.streetproof.alert_subscription.v1'
  - `ok` boolean
  - `subscription` object
    - `public_id` string
    - `status` 'pending' | 'active' | 'paused' | 'unsubscribed'
    - `created` boolean
    - `channel` 'email' | 'dashboard' | 'webhook'
    - `scope` object
    - `event_types` string[]
    - `min_confidence` number
  - `delivery` object
    - `status` 'verification_pending' | 'partner_portal_pending'
    - `queued_events` integer
    - `note` string
  - `preview` object
    - `matched_events` integer
    - `latest_events` object[]

## Other responses

- `201`: Subscription created
- `400`: Invalid parameter.
- `404`: Resource not found (or entity opted out).

---

[API](https://skmtc.dev/streetproof/apis/streetproof-physical-brand-index-api.md) · [All operations](https://skmtc.dev/streetproof/apis/streetproof-physical-brand-index-api/llms.txt) · [OpenAPI document](https://skmtc.dev/streetproof/apis/streetproof-physical-brand-index-api/revisions/81072718cfa2?raw)