> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.jazzhq.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.jazzhq.ai/_mcp/server.

# Lead commands

`lead list` and `lead create` take a `partner_id`, because leads belong to a partner
and a new one has to be filed against one. Every other command takes only the
`lead_id` — a lead id is unique on its own.

## `jazzhq-cli lead list`

List a partner's leads, newest first. Archived leads are excluded unless you ask for them.

| Argument / Flag           | Required | Default     | Description                                     |
| ------------------------- | -------- | ----------- | ----------------------------------------------- |
| `partner_id` (positional) | yes      |             | The partner's ID                                |
| `--page`                  | no       | `0`         | Page number                                     |
| `--per-page`              | no       | `20`        | Results per page, up to `100`                   |
| `--sort-by`               | no       | `createdAt` | One of `id`, `createdAt`, `updatedAt`           |
| `--sort-direction`        | no       | `desc`      | `asc` or `desc`                                 |
| `--approval-status`       | no       |             | One of `PENDING`, `APPROVED`, `REJECTED`        |
| `--status`                | no       |             | Id of a lead status dropdown value. Repeatable. |
| `--source`                | no       |             | Id of a lead source dropdown value. Repeatable. |
| `--keyword`               | no       |             | Prefix match on first name or email address     |
| `--created-at-after`      | no       |             | `YYYY-MM-DD`                                    |
| `--created-at-before`     | no       |             | `YYYY-MM-DD`                                    |
| `--archived`              | no       |             | List archived leads instead of active ones      |
| `--api-key`               | no       |             | Overrides `JAZZHQ_API_KEY`                      |
| `--base-url`              | no       |             | Overrides `JAZZHQ_API_BASE_URL`                 |

```bash
jazzhq-cli lead list 1001 --approval-status PENDING --per-page 50
```

```bash
jazzhq-cli lead list 1001 \
  --created-at-after 2026-08-01 \
  --created-at-before 2026-08-31 \
  --status 10 --status 11
```

> **Note**
>
> Sorting is always tie-broken by `id`, so paging through a large result set never skips or
> repeats a lead. A `--per-page` above `100` exits `2` without calling the API.

## `jazzhq-cli lead get`

Fetch a single lead.

```bash
jazzhq-cli lead get 300
```

A lead belonging to a different partner returns `RESOURCE_NOT_FOUND`, exactly as one that
does not exist — so a lead ID alone never reveals whether it exists.

## `jazzhq-cli lead create`

Create a lead for a partner.

| Argument / Flag                  | Required | Description                                |
| -------------------------------- | -------- | ------------------------------------------ |
| `partner_id` (positional)        | yes      | The partner's ID                           |
| `--first-name`                   | yes      | Lead's first name                          |
| `--email-address`                | yes      | Lead's email address                       |
| `--company-name`                 | yes      | Lead's company name                        |
| `--last-name`                    | no       | Lead's last name                           |
| `--phone-number`                 | no       | Lead's phone number                        |
| `--linked-in-url`                | no       | Lead's LinkedIn profile URL                |
| `--website-url`                  | no       | Lead's company website                     |
| `--company-size`                 | no       | Lead's company size, e.g. `50-100`         |
| `--industry`                     | no       | Lead's industry                            |
| `--job-title`                    | no       | Lead's job title                           |
| `--city`, `--state`, `--country` | no       | Lead's location                            |
| `--source`                       | no       | Id of a lead source dropdown value         |
| `--status`                       | no       | Id of a lead status dropdown value         |
| `--lead-age`                     | no       | Age of the lead in days                    |
| `--products-interested`          | no       | Products the lead is interested in         |
| `--business-impact-metrics`      | no       | Expected business impact                   |
| `--external-id`                  | no       | Your own identifier, echoed back unchanged |
| `--api-key`                      | no       | Overrides `JAZZHQ_API_KEY`                 |
| `--base-url`                     | no       | Overrides `JAZZHQ_API_BASE_URL`            |

```bash
jazzhq-cli lead create 1001 \
  --first-name "Jane" \
  --email-address "jane@acme.com" \
  --company-name "Acme Inc" \
  --job-title "VP Sales" \
  --external-id "crm-42"
```

The lead is created against the partner in the path and the vendor your API key belongs
to; neither is read from your input. An email address already used by another of that
partner's leads exits `1` with `DUPLICATE_ENTRY`.

## `jazzhq-cli lead update`

Update a lead. Only the fields you pass change; everything else keeps its stored value.
Use `lead replace` when you want the fields you omit cleared instead.

Takes `lead_id` as its only positional, then the same optional field flags as
`lead create`. The lead id is unique on its own — no partner id needed.

```bash
jazzhq-cli lead update 300 --job-title "Head of Sales"
```

> **Note**
>
> Approval state and archiving cannot be set here — use `lead approve`, `lead reject` and
> `lead archive`. Passing no fields at all exits `2` rather than sending an empty request.

## `jazzhq-cli lead replace`

Replace a lead with a full object. Any field you leave off is **cleared**, so this expects
the whole record rather than just what changed. Prefer `lead update` unless you
specifically want that clearing behaviour.

Takes `lead_id` as its only positional. `--first-name`, `--email-address` and
`--company-name` are required, exactly as on `lead create`; every other field flag is
optional, and any you omit is sent as null.

```bash
jazzhq-cli lead replace 300 \
  --first-name Ada \
  --email-address ada@example.com \
  --company-name "X Ltd" \
  --job-title "VP Sales"
```

After that call the lead holds only the four fields given — a previously stored `--city`
or `--phone-number` is cleared.

> **Note**
>
> Approval state and archiving are never affected by a replace, the same as with
> `lead update` — use `lead approve`, `lead reject` and `lead archive`.

## `jazzhq-cli lead archive`

Archive a lead, hiding it from listings without deleting it.

```bash
jazzhq-cli lead archive 300
```

Safe to run twice — archiving an already-archived lead succeeds and changes nothing.

## `jazzhq-cli lead approve`

Approve a lead and convert it into a contact. Prints the lead and the `contactId` it
became.

```bash
jazzhq-cli lead approve 300
```

```json
{
  "success": true,
  "message": "LEAD_APPROVE_SUCCESSFUL",
  "data": {
    "lead": { "id": 300, "approvalStatus": "APPROVED" },
    "contactId": 500
  },
  "timestamp": "2026-08-01T09:15:00"
}
```

Safe to retry: approving an already-approved lead returns the same contact rather than
creating another. Approving a rejected lead exits `1` with `INVALID_STATE_TRANSITION`.

## `jazzhq-cli lead reject`

Reject a lead, optionally recording why.

| Argument / Flag        | Required | Description                     |
| ---------------------- | -------- | ------------------------------- |
| `lead_id` (positional) | yes      | The lead's ID                   |
| `--comment`            | no       | Reason for the rejection        |
| `--api-key`            | no       | Overrides `JAZZHQ_API_KEY`      |
| `--base-url`           | no       | Overrides `JAZZHQ_API_BASE_URL` |

```bash
jazzhq-cli lead reject 300 --comment "No budget this quarter"
```

Rejecting twice keeps the first comment. Rejecting an approved lead exits `1` with
`INVALID_STATE_TRANSITION`.

## A typical flow

```bash
# 1. See what a partner has submitted recently
jazzhq-cli lead list 1001 --approval-status PENDING

# 2. Look at one in full
jazzhq-cli lead get 300

# 3. Correct something before deciding
jazzhq-cli lead update 300 --job-title "Head of Sales"

# 4. Approve it, converting it into a contact
jazzhq-cli lead approve 300

# ...or turn it down, with a reason
jazzhq-cli lead reject 301 --comment "Outside our target market"

# 5. Tidy up something that is no longer relevant
jazzhq-cli lead archive 302
```