# Recommendations

## Get All Upscribe Recommendations

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v2/upscribes/:identifier/recommendations`

Returns all recommendations for an Upscribe, including paused ones. Recommendations are ordered in descending order by *created\_at*, meaning the first page shows the latest recommendations.

#### Path Parameters

| Name                                         | Type   | Description   |
| -------------------------------------------- | ------ | ------------- |
| identifier<mark style="color:red;">\*</mark> | String | Upscribe UUID |

#### Query Parameters

| Name      | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| page      | integer | Results page to return. Default is 1               |
| per\_page | integer | How many results to return per page. Default is 50 |

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

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

{% endtab %}

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

```json
{ "error": "Upscribe upscribe_38yhewu92 not found." }
```

{% endtab %}

{% tab title="400: Bad Request When Upscribe is not active" %}

```json
{ "error": "Upscribe upscribe_9uewihsi9 is not active." }
```

{% endtab %}
{% endtabs %}

## Generate recommendations

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v2/upscribes/:identifier/recommendations`

#### Path Parameters

| Name                                         | Type   | Description   |
| -------------------------------------------- | ------ | ------------- |
| identifier<mark style="color:red;">\*</mark> | String | Upscribe UUID |

#### Request Body

| Name          | Type    | Description                                                                                                                                                                                                                                                                                                                                                              |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| country\_code | String  | <p>Subscriber's <a href="https://www.iban.com/country-codes">ISO 3166-1 Alpha2 country code</a>.<br><br>Eg: US, IT<br><br>Optional but VERY important. Without it, we can't generate the correct recommendations.<br><br></p>                                                                                                                                            |
| region\_code  | String  | <p>Subscriber's ISO 3166-2 state or region code.<br><br>Eg: TX, CA<br><br>Less important than the country code but some of our advertisers only target specific states and if you don’t pass the state code our system will not generate recommendations for those advertisers</p>                                                                                       |
| limit         | Integer | <p>How many recommendations you want to generate. To avoid inflating numbers, which then negatively impact your performance, always generate the number of recommendations you're going to display.<br><br>If no limit is passed 1 recommendation will be returned.<br><br>The maximum allowed value is 20. If a higher value is provided, it will be clamped to 20.</p> |

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

```json
{
  "recommendations": [
    <Recommendation Object>,
    <Recommendation Object>,
    <Recommendation Object>,
  ]
}
```

{% endtab %}
{% endtabs %}

## Edit Recommendation

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v2/upscribes/:identifier/recommendations/:recommendation_identifier`

#### Path Parameters

| Name                                                         | Type   | Description         |
| ------------------------------------------------------------ | ------ | ------------------- |
| identifier<mark style="color:red;">\*</mark>                 | String | Upscribe UUID       |
| recommendation\_identifier<mark style="color:red;">\*</mark> | String | Recommendation UUID |

#### Request Body

| Name                                     | Type   | Description                                                  |
| ---------------------------------------- | ------ | ------------------------------------------------------------ |
| reason<mark style="color:red;">\*</mark> | String | This is what will be displayed in the recommendation widget. |

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

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

{% endtab %}
{% endtabs %}

## Pin Recommendation

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v2/upscribes/:identifier/recommendations/:recommendation_identifier/pin`

#### Path Parameters

| Name                                                         | Type   | Description         |
| ------------------------------------------------------------ | ------ | ------------------- |
| identifier<mark style="color:red;">\*</mark>                 | String | Upscribe UUID       |
| recommendation\_identifier<mark style="color:red;">\*</mark> | String | Recommendation UUID |

{% tabs %}
{% tab title="200 Returns upscribe recommendation" %}

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

{% endtab %}
{% endtabs %}

## Unpin Recommendation

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v2/upscribes/:identifier/recommendations/:recommendation_identifier/unpin`

#### Path Parameters

| Name                                                         | Type   | Description         |
| ------------------------------------------------------------ | ------ | ------------------- |
| identifier<mark style="color:red;">\*</mark>                 | String | Upscribe UUID       |
| recommendation\_identifier<mark style="color:red;">\*</mark> | String | Recommendation UUID |

{% tabs %}
{% tab title="200 Returns upscribe recommendation" %}

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

{% endtab %}
{% endtabs %}

## Pause Recommendation

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v2/upscribes/:identifier/recommendations/:recommendation_identifier/pause`

#### Path Parameters

| Name                                                         | Type   | Description         |
| ------------------------------------------------------------ | ------ | ------------------- |
| identifier<mark style="color:red;">\*</mark>                 | String | Upscribe UUID       |
| recommendation\_identifier<mark style="color:red;">\*</mark> | String | Recommendation UUID |

{% tabs %}
{% tab title="200 Returns upscribe recommendation" %}

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

{% endtab %}
{% endtabs %}

## Unpause Recommendation

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v2/upscribes/:identifier/recommendations/:recommendation_identifier/unpause`

#### Path Parameters

| Name                                                         | Type   | Description         |
| ------------------------------------------------------------ | ------ | ------------------- |
| identifier<mark style="color:red;">\*</mark>                 | String | Upscribe UUID       |
| recommendation\_identifier<mark style="color:red;">\*</mark> | String | Recommendation UUID |

{% tabs %}
{% tab title="200 Returns upscribe recommendation" %}

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

{% endtab %}
{% endtabs %}