> 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 | Flow status.                                                                   |
| `created_at`           | String | When the flow was created (ISO 8601).                                          |
| `display`              | Object | Which stages the flow shows: `recommendations`, `offers`, `survey` (booleans). |
| `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`.                        |

**`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`**

One of four mutually exclusive types via `type`: `show_thank_you`, `redirect_to_url` (adds `redirect_url`), `close_widget`, or `custom_rules` (adds `rules`, a per-page list of `{ page_url, type, redirect_url? }`).

**`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": "suf_6a7b8c",
  "status": "active",
  "created_at": "2025-02-10T00:00:00.000Z",
  "display": { "recommendations": true, "offers": true, "survey": true },
  "visibility": { "all_pages": true, "page_rules": [] },
  "completion_behaviour": { "type": "show_thank_you" }
}
```

**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.085,
    "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.66 },
    "offers": {
      "impressions": 5400,
      "earnings": 120.0,
      "earnings_per_visit": 0.015,
      "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.085,
    "recommendations": {
      "impressions": 3500,
      "earnings": { "confirmed": 220.0, "estimated_pending": 40.0, "total": 260.0 },
      "earnings_per_visit": 0.065,
      "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 }
    }
  }
}
```