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

# Create a stream

> One-shot create: accounts + segments + schedule + delivery in one call

Creates a new campaign (stream) in one call. Resolves new handles via ScrapeBadger (upserting tracked accounts + incrementing Stripe quantity), creates inline segments if provided, wires pairs through the segment-cap chokepoint.

## Body

| Field                 | Type              | Description                                                                                                                                                        |
| --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                | string (optional) | Campaign name. If omitted, the server derives one from the resolved pairs: `"{segment} · @{handle}"` for a single account, `"{segment} · N accounts"` for several. |
| `pairs`               | array             | Up to 50 `(account, segment)` pairs                                                                                                                                |
| `syncTimes`           | array             | `["HH:MM"]` slots (15-min boundaries). Default: one hash-distributed slot.                                                                                         |
| `timezone`            | string            | IANA timezone. Default: user's default or `"UTC"`.                                                                                                                 |
| `autoEnrichLinkedin`  | boolean           | Auto-enrich LinkedIn URL on new leads. Default `false`.                                                                                                            |
| `autoEnrichEmail`     | boolean           | Auto-enrich email on new leads. Default `false`.                                                                                                                   |
| `emailMode`           | enum              | `"verified"` or `"any"`. Default `"any"`.                                                                                                                          |
| `emailDigestOverride` | enum              | `"after_every_sync"`, `"daily"`, `"weekly"`, `"off"`                                                                                                               |
| `telegramOverride`    | boolean           | Override team-default Telegram digest setting                                                                                                                      |
| `deliveryDestination` | enum              | `"leads_only"` or `"leads_plus_webhook"`                                                                                                                           |
| `webhookUrl`          | string            | URL for webhook delivery (when `deliveryDestination = "leads_plus_webhook"`)                                                                                       |
| `csvEmailRecipients`  | object            | `{to, cc?, format}` for "email me a CSV after every run"                                                                                                           |

Each pair specifies an account (by `accountId` OR `accountHandle`) AND a segment (by `segmentId` OR inline `segment`):

```json theme={null}
{
  "accountId": 7,
  "segmentId": 12
}
```

OR

```json theme={null}
{
  "accountHandle": "yongfook",
  "accountTier": "starter",
  "segment": {
    "description": "AI founders building developer tools",
    "appliedSearchFilters": { "job_role": ["Founder", "CEO"] }
  }
}
```

## Response

```json theme={null}
{
  "id": 42,
  "accounts": [
    { "handle": "yongfook", "accountId": 7, "accountCreated": true, "billingDelta": "stripe_quantity_incremented" }
  ],
  "segments": [
    { "segmentId": 12, "segmentCreated": true }
  ]
}
```

## Error codes

| Code                    | HTTP | When                                                                    |
| ----------------------- | ---- | ----------------------------------------------------------------------- |
| `handle_not_found`      | 404  | X handle didn't resolve                                                 |
| `handle_protected`      | 422  | Handle is a private account                                             |
| `handle_lookup_failed`  | 503  | X lookup service down                                                   |
| `free_account_limit`    | 403  | Free user adding 2nd account                                            |
| `subscription_required` | 403  | Paid user with lapsed sub                                               |
| `stream_cap_exceeded`   | 400  | Tier cap of automated streams per account exceeded                      |
| `stream_multi_segment`  | 400  | Pairs span more than one segment (a stream targets exactly one segment) |
| `orphan_label`          | 400  | Inline segment had labels with no canonical match                       |

## Auth

Bearer or session cookie.