> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credentialsportal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Broadcasts

> Send district-wide announcements to specific people via the API.

Broadcasts are one-way announcements sent to an explicit list of recipients. Recipients are notified via email and push notification (based on their preferences).

<Note>
  Requires the **Broadcasts** permission (`g: 1`) on the caller's role.
</Note>

## List broadcasts

```bash theme={null}
GET /api/broadcasts
```

Returns the 50 most recent broadcasts sent from your district, most recent first.

**Example:**

```bash theme={null}
curl https://app.credentialsportal.com/api/broadcasts \
  -H "Authorization: Bearer ck_your_api_key"
```

**Response:**

```json theme={null}
{
  "broadcasts": [
    {
      "id": "brd01",
      "subject": "District Assembly Reminder",
      "body": "<p>Please join us for District Assembly on March 15...</p>",
      "sender_id": "abc12",
      "sender_name": "Jane Doe",
      "recipient_ids": ["def34", "ghi56"],
      "sent_count": 12,
      "opened_count": 7,
      "created_at": 1741564800000
    }
  ]
}
```

`opened_count` is `null` for broadcasts sent before open tracking was enabled.

***

## Send a broadcast

```bash theme={null}
POST /api/broadcasts
```

**Request body:**

<ParamField body="recipientIds" type="array" required>
  An array of person IDs to send the broadcast to. The sender is automatically excluded.
</ParamField>

<ParamField body="subject" type="string" required>
  The broadcast subject line (used in email delivery).
</ParamField>

<ParamField body="body" type="string" required>
  The broadcast body. Supports HTML markup.
</ParamField>

**Example:**

```bash theme={null}
curl -X POST https://app.credentialsportal.com/api/broadcasts \
  -H "Authorization: Bearer ck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientIds": ["def34", "ghi56", "jkl78"],
    "subject": "Interview Schedule Update",
    "body": "<p>Board interviews are scheduled for April 5. Please confirm your attendance.</p>"
  }'
```

**Response:**

```json theme={null}
{
  "ok": true,
  "id": "brd02",
  "sent": 3
}
```

Email and push delivery happen in the background after the response is returned. `sent` reflects the number of unique recipients (excluding the sender).

***

## Get broadcast stats

```bash theme={null}
GET /api/broadcasts/:id/stats
```

Returns open and delivery statistics for a broadcast, sourced from email delivery tracking. Stats are cached and may be up to a few minutes old for recent broadcasts.

**Example:**

```bash theme={null}
curl https://app.credentialsportal.com/api/broadcasts/brd02/stats \
  -H "Authorization: Bearer ck_your_api_key"
```

**Response:**

```json theme={null}
{
  "opened": 5,
  "delivered": 10,
  "checkedAt": 1741564800000
}
```

`opened` and `delivered` are `null` if tracking data isn't available for the broadcast. A `cached: true` field is included when the response was served from cache.

***

## Get broadcasts for a person

```bash theme={null}
GET /api/broadcasts/people/:id
```

Returns the 20 most recent broadcasts received by a specific person. Requires admin permissions, or the person themselves.

**Example:**

```bash theme={null}
curl https://app.credentialsportal.com/api/broadcasts/people/def34 \
  -H "Authorization: Bearer ck_your_api_key"
```

**Response:**

```json theme={null}
{
  "broadcasts": [
    {
      "id": "brd01",
      "subject": "District Assembly Reminder",
      "body": "<p>Please join us for District Assembly on March 15...</p>",
      "sender_id": "abc12",
      "sender_name": "Jane Doe",
      "created_at": 1741564800000
    }
  ]
}
```