> 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/offers.md).

# Offers

## Offers

The partner-side catalog of offers a publication can join. Browse and filter the available offers, then **recommend** (join) one — which creates a joined offer, listed under **Earn › Offers**.

### Browse the directory

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

Paginated.

**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                                                                                                                                                |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q                 | String | Free-text search across offer headline, brand, and publication name.                                                                                       |
| categories        | Array  | Filter by offer category. One or more of: `b2b`, `education`, `finance`, `food_and_drink`, `health_fitness`, `kids_family`, `shopping_lifestyle`, `other`. |
| conversion\_types | Array  | Filter by conversion type. One or more of: `lead`, `click`, `action`.                                                                                      |
| commission\_type  | String | Filter by commission type: `fixed` or `percentage`.                                                                                                        |
| countries         | String | Comma-separated ISO country codes (e.g. `US,CA`). Returns offers that accept referrals from any of them.                                                   |
| sort              | String | `newest` (most recently activated). Defaults to a tiered payout ranking.                                                                                   |

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

```json
{
  "offers": [
    <Directory Offer Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 3,
    "total_offers": 118
  }
}
```

{% endtab %}
{% endtabs %}

### Get a directory offer

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

**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 offer's UUID.       |

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

```json
{
  "offer": <Directory Offer Object>
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

### Recommend an offer

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

Joins the offer, returning it as a newly created joined offer.

**Path Parameters**

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

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

```json
{
  "offer": <Offer Recommendation Object>
}
```

{% endtab %}

{% tab title="409: Conflict" %}

```json
{
  "error": "Offer already added"
}
```

{% endtab %}
{% endtabs %}