> 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/earn/directory/recommendations.md).

# Recommendations

## Recommendations

The Partner Network directory of partner programs a publisher can join to earn by recommending. Browse the catalog, then **recommend** (join) a program. The joined recommendations themselves are listed under **Earn › Recommendations**.

### Browse the directory

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

Paginated. Each row includes `already_recommended` — whether this publication already has a non-archived paid recommendation for that program.

**Path Parameters**

| Name                                                | Type   | Description                                    |
| --------------------------------------------------- | ------ | ---------------------------------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication a join would be attributed to. |

**Query Parameters**

| Name                 | Type    | Description                                                                         |
| -------------------- | ------- | ----------------------------------------------------------------------------------- |
| order\_by            | String  | `commission` or `max_payout`. Defaults to newest first.                             |
| exclude\_recommended | Boolean | When `true`, omit programs this publication already recommends (non-archived paid). |

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

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

{% endtab %}
{% endtabs %}

### Get a directory entry

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

On a single entry the object also carries `pre_approved` — whether this publication is auto-approved to join. `already_recommended` is present as on the list.

**Path Parameters**

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

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

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

### Recommend a program

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/earn/directory/recommendations/:recommendation_uuid/recommend`

Starts recommending the program's publication. Returns the created **Recommendation** — `status` is `active` when pre-approved, or `awaiting_approval` when the program screens partners.

**Path Parameters**

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

**Request Body**

| Name                      | Type   | Description                                                        |
| ------------------------- | ------ | ------------------------------------------------------------------ |
| reason\_for\_recommending | String | The applicant's pitch. Required when the program screens partners. |

{% tabs %}
{% tab title="201: Created" %}

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

{% endtab %}

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

```json
{
  "error": "You are already recommending this publication."
}
```

{% endtab %}
{% endtabs %}