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

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`).

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