> 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/endpoints/publications/tools/signup-flow.md).

# Signup Flow

## Signup Flow

A **Signup Flow** is a publication's on-site subscriber flow — the widget (or hosted page) that greets new subscribers and walks them through recommendations, an optional survey, and offers. Each publication has exactly one, so this is a singleton resource.

### Get signup flow

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/signup_flow`

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

**Query Parameters**

| Name                | Type   | Description                                                                                                                                                                                      |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| expand              | String | `stats` to include per-step performance.                                                                                                                                                         |
| from                | String | Start date (`YYYY-MM-DD`) for `stats`.                                                                                                                                                           |
| to                  | String | End date (`YYYY-MM-DD`) for `stats`.                                                                                                                                                             |
| stats\_grouped\_by  | String | With `expand=stats`, group the stats map by `utm_source`, `utm_campaign`, or `country_code`. Top 50 groups by visit volume. Blank/missing values appear under `"none"`. Requires `expand=stats`. |
| stats\_group\_value | String | Optional. With `stats_grouped_by`, return only that one group key (a one-key map). Use `"none"` for blank/missing. Requires `stats_grouped_by`.                                                  |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "signup_flow": <Signup Flow Object>
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
  "error": "Unsupported `stats_grouped_by`. Valid values: utm_source, utm_campaign, country_code."
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}
{% endtabs %}

### Enable recommendations stage

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/signup_flow/recommendations/activation`

Shows the recommendations stage to new subscribers.

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "signup_flow": <Signup Flow Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}
{% endtabs %}

### Disable recommendations stage

<mark style="color:red;">`DELETE`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/signup_flow/recommendations/activation`

Hides the recommendations stage. At least one of recommendations or offers must remain enabled.

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "signup_flow": <Signup Flow Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```json
{
  "error": "You must display either recommendations or offers"
}
```

{% endtab %}
{% endtabs %}

### Enable offers stage

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/signup_flow/offers/activation`

Shows the offers stage to new subscribers.

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "signup_flow": <Signup Flow Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}
{% endtabs %}

### Disable offers stage

<mark style="color:red;">`DELETE`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/signup_flow/offers/activation`

Hides the offers stage. At least one of recommendations or offers must remain enabled.

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "signup_flow": <Signup Flow Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```json
{
  "error": "You must display either recommendations or offers"
}
```

{% endtab %}
{% endtabs %}

### Enable survey stage

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/signup_flow/survey/activation`

Shows the survey stage to new subscribers. The publication must already have a survey.

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "signup_flow": <Signup Flow Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```json
{
  "error": "Display survey can't be enabled without a survey"
}
```

{% endtab %}
{% endtabs %}

### Disable survey stage

<mark style="color:red;">`DELETE`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/signup_flow/survey/activation`

Hides the survey stage.

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "signup_flow": <Signup Flow Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}
{% endtabs %}