> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/api-v3/objects-schema/signup-flow-object.md).

# Signup Flow Object

## Signup Flow Object

A publication's on-site subscriber flow.

| Field                  | Type   | Description                                                       |
| ---------------------- | ------ | ----------------------------------------------------------------- |
| `uuid`                 | String | Signup flow UUID.                                                 |
| `status`               | String | `draft`, `active` or `paused`. Read-only. See below.              |
| `created_at`           | String | When the flow was created (ISO 8601).                             |
| `recommendations`      | Object | The recommendations stage (see below).                            |
| `offers`               | Object | The offers stage (see below).                                     |
| `survey`               | Object | The survey stage (see below).                                     |
| `hosted_page_url`      | String | The hosted page URL. Present only when the flow is a hosted page. |
| `visibility`           | Object | Where the widget shows (see below).                               |
| `completion_behaviour` | Object | What happens after a subscriber finishes (see below).             |
| `stats`                | Object | Per-step performance. Present only with `expand=stats`.           |

**`status`**

| Value    | Meaning                        |
| -------- | ------------------------------ |
| `draft`  | The flow is not launched yet.  |
| `active` | The flow is launched.          |
| `paused` | The flow stopped after launch. |

**`recommendations`**

| Field     | Type    | Description                                                                                                                                                             |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `display` | Boolean | Whether the flow shows the recommendations stage. See [Recommendations](https://docs.sparkloop.app/api-v3/endpoints/publications/tools/signup-flow/recommendations.md). |
| `slots`   | Array   | Present only with `expand=slots`. In position order. Each is a [Slot Object](https://docs.sparkloop.app/api-v3/objects-schema/slot-object.md).                          |

**`offers`**

| Field                 | Type    | Description                                                                                                                                    |
| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `display`             | Boolean | Whether the flow shows the offers stage. See [Offers](https://docs.sparkloop.app/api-v3/endpoints/publications/tools/signup-flow/offers.md).   |
| `slots`               | Array   | Present only with `expand=slots`. In position order. Each is a [Slot Object](https://docs.sparkloop.app/api-v3/objects-schema/slot-object.md). |
| `nudge_email.enabled` | Boolean | `true` when the offers nudge email is on. It emails a subscriber who chose a click or action offer a link to complete it.                      |

**`survey`**

| Field                 | Type    | Description                                                                                                                                        |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `display`             | Boolean | Whether the flow shows the survey stage. See [Survey](https://docs.sparkloop.app/api-v3/endpoints/publications/tools/signup-flow/survey.md).       |
| `nudge_email.enabled` | Boolean | Whether the survey nudge email is on. It emails a subscriber who saw the survey and did not submit it. `false` when the publication has no survey. |

**`visibility`**

| Field        | Type    | Description                                                                          |
| ------------ | ------- | ------------------------------------------------------------------------------------ |
| `all_pages`  | Boolean | Whether the widget shows on every page.                                              |
| `page_rules` | Array   | Specific page URLs it shows on (empty when `all_pages` is true or on a hosted page). |

**`completion_behaviour`**

| Field          | Type   | Description                                                            |
| -------------- | ------ | ---------------------------------------------------------------------- |
| `type`         | String | `show_thank_you`, `redirect_to_url`, `close_widget` or `custom_rules`. |
| `redirect_url` | String | `redirect_to_url` only.                                                |
| `rules`        | Array  | `custom_rules` only. Rules, in the order they were sent (see below).   |
| `default`      | Object | `custom_rules` only. What applies when no rule matches (see below).    |

Every URL in `completion_behaviour` is returned with `https://`.

To change it, see [Completion Behaviour](https://docs.sparkloop.app/api-v3/endpoints/publications/tools/signup-flow/completion-behaviour.md).

**`completion_behaviour.rules[]`**

| Field          | Type   | Description                                                                          |
| -------------- | ------ | ------------------------------------------------------------------------------------ |
| `page_url`     | String | The page the rule applies to. `*` is a wildcard. Lowercased, without a trailing `/`. |
| `type`         | String | `show_thank_you`, `redirect_to_url` or `close_widget`.                               |
| `redirect_url` | String | `redirect_to_url` only. Lowercased, without a trailing `/`.                          |

**`completion_behaviour.default`**

| Field          | Type   | Description                            |
| -------------- | ------ | -------------------------------------- |
| `type`         | String | `show_thank_you` or `redirect_to_url`. |
| `redirect_url` | String | `redirect_to_url` only.                |

**`stats`** (only with `expand=stats`)

By default, `stats` is a flat object: an overall block (`visits`, `earnings`, `earnings_per_visit`) plus one block per stage — `recommendations` (`impressions`, `earnings`, `earnings_per_visit`, `referrals` split into `confirmed_paid`/`pending_paid`/`free`/`total`), `survey` (`impressions`, `completions`, `completions_per_visit`), and `offers` (`impressions`, `earnings`, `earnings_per_visit`, `claims` split into `confirmed_paid`/`pending_paid`/`internal_free`/`total`).

**Grouped `stats`** (with `stats_grouped_by`)

On **Get signup flow**, pass `stats_grouped_by=utm_source`, `utm_campaign`, or `country_code` with `expand=stats` to get the same per-stage shape nested under each group key. Results are capped at the top 50 groups by visit volume. Blank or missing values appear under `"none"`. Optionally pass `stats_group_value` to return a one-key map for that group only.

**Example**

```json
{
  "uuid": "upscribe_6a7b8c4d2e1f",
  "status": "active",
  "created_at": "2025-02-10T00:00:00Z",
  "recommendations": { "display": true },
  "offers": {
    "display": true,
    "nudge_email": { "enabled": true }
  },
  "survey": { "display": true, "nudge_email": { "enabled": true } },
  "visibility": { "all_pages": true, "page_rules": [] },
  "completion_behaviour": {
    "type": "custom_rules",
    "rules": [
      { "page_url": "https://example.com/pricing", "type": "close_widget" },
      { "page_url": "https://example.com/blog", "type": "redirect_to_url", "redirect_url": "https://example.com/thanks" }
    ],
    "default": { "type": "redirect_to_url", "redirect_url": "https://example.com/thanks" }
  }
}
```

**Example `slots` (`expand=slots`)**

```json
{
  "recommendations": {
    "display": true,
    "slots": [
      { "position": 1, "type": "earning_optimized" },
      { "position": 2, "type": "specific", "recommendation_uuid": "partner_campaign_3f9a1c7e5b2d" }
    ]
  },
  "offers": {
    "display": true,
    "slots": [
      { "position": 1, "type": "specific", "offer_uuid": "offer_recommendation_65dbdd0923b1" }
    ],
    "nudge_email": { "enabled": true }
  }
}
```

**Example `stats` (`expand=stats`)**

```json
{
  "visits": 12000,
  "earnings": { "confirmed": 900.0, "estimated_pending": 120.0, "total": 1020.0 },
  "earnings_per_visit": 0.085,
  "recommendations": {
    "impressions": 11000,
    "earnings": { "confirmed": 700.0, "estimated_pending": 120.0, "total": 820.0 },
    "earnings_per_visit": 0.068,
    "referrals": { "confirmed_paid": 300, "pending_paid": 60, "free": 140, "total": 500 }
  },
  "survey": { "impressions": 9000, "completions": 6400, "completions_per_visit": 0.53 },
  "offers": {
    "impressions": 8000,
    "earnings": 200.0,
    "earnings_per_visit": 0.017,
    "claims": { "confirmed_paid": 90, "pending_paid": 20, "internal_free": 30, "total": 140 }
  }
}
```

**Example grouped `stats` (`expand=stats&stats_grouped_by=utm_source`)**

```json
{
  "twitter": {
    "visits": 8000,
    "earnings": { "confirmed": 600.0, "estimated_pending": 80.0, "total": 680.0 },
    "earnings_per_visit": 0.09,
    "recommendations": {
      "impressions": 7500,
      "earnings": { "confirmed": 480.0, "estimated_pending": 80.0, "total": 560.0 },
      "earnings_per_visit": 0.07,
      "referrals": { "confirmed_paid": 200, "pending_paid": 40, "free": 90, "total": 330 }
    },
    "survey": { "impressions": 6200, "completions": 4100, "completions_per_visit": 0.51 },
    "offers": {
      "impressions": 5400,
      "earnings": 120.0,
      "earnings_per_visit": 0.02,
      "claims": { "confirmed_paid": 60, "pending_paid": 12, "internal_free": 18, "total": 90 }
    }
  },
  "none": {
    "visits": 4000,
    "earnings": { "confirmed": 300.0, "estimated_pending": 40.0, "total": 340.0 },
    "earnings_per_visit": 0.09,
    "recommendations": {
      "impressions": 3500,
      "earnings": { "confirmed": 220.0, "estimated_pending": 40.0, "total": 260.0 },
      "earnings_per_visit": 0.07,
      "referrals": { "confirmed_paid": 100, "pending_paid": 20, "free": 50, "total": 170 }
    },
    "survey": { "impressions": 2800, "completions": 2300, "completions_per_visit": 0.58 },
    "offers": {
      "impressions": 2600,
      "earnings": 80.0,
      "earnings_per_visit": 0.02,
      "claims": { "confirmed_paid": 30, "pending_paid": 8, "internal_free": 12, "total": 50 }
    }
  }
}
```
