> 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/grow/free-recommendations.md).

# Free Recommendations

## Free Recommendations

A **free recommendation** is an organic newsletter partnership with no payment (the Grow side). Unlike paid recommendations, the same campaign can be **sending** (this publication recommends the other) or **receiving** (the other recommends this one). This resource unions both sides.

Use it to list free recommendations, fetch a single one by UUID, archive, or re-activate. Filter the list with `role=sending` or `role=receiving`; omit `role` for both. Each row includes `role` relative to this publication, plus `recommending_publication` next to `recommended_publication`. To browse newsletters available to recommend — and to **add a recommendation** or **send a partnership request** — use the **Directory** at `grow/directory/free_recommendations`. Paid recommendations live under **Earn**.

### List free recommendations

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

Paginated. Omit `status` to list non-archived rows. Omit `role` to include both sending and receiving.

**Path Parameters**

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

**Query Parameters**

| Name   | Type   | Description                                                                                                |
| ------ | ------ | ---------------------------------------------------------------------------------------------------------- |
| status | String | Optional filter: `active`, `awaiting_approval`, or `archived`. Omit for all non-archived. Invalid → `400`. |
| role   | String | Optional filter: `sending` or `receiving`. Omit for both. Invalid → `400`.                                 |
| expand | String | `recommended_publication`, `recommending_publication`, `stats`.                                            |
| from   | String | Start date (`YYYY-MM-DD`) for `stats`.                                                                     |
| to     | String | End date (`YYYY-MM-DD`) for `stats`.                                                                       |

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

```json
{
  "recommendations": [
    <Recommendation Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 1,
    "total_recommendations": 12
  }
}
```

{% endtab %}

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

```json
{
  "error": "Unsupported `status`. Valid values: active, awaiting_approval, archived."
}
```

{% endtab %}
{% endtabs %}

### Get free recommendation

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

Fetch a single free recommendation this publication sends or receives.

**Path Parameters**

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

**Query Parameters**

| Name   | Type   | Description                                                     |
| ------ | ------ | --------------------------------------------------------------- |
| expand | String | `recommended_publication`, `recommending_publication`, `stats`. |

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

```json
{
  "recommendation": <Recommendation Object>
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

### Archive a free recommendation

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/grow/free_recommendations/:free_recommendation_uuid/archive`

Soft-archives the recommendation so it stops appearing in active lists. Sending archives as the partner; receiving archives as the sponsor. Reversible with **re-activate** when this publication archived it.

**Path Parameters**

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

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

```json
{
  "recommendation": <Recommendation Object>
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

### Re-activate a free recommendation

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/grow/free_recommendations/:free_recommendation_uuid/reactivation`

Restores a soft-archived free recommendation. Only works when **this publication** archived it.

**Path Parameters**

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

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

```json
{
  "recommendation": <Recommendation Object>
}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
  "error": "This recommendation was archived by the other publication and can't be re-activated."
}
```

{% endtab %}
{% endtabs %}