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

# Campaigns

## Campaigns

A **Campaign** is a uniquely tracked link a publication places in its emails. SparkLoop attributes the clicks each link drives — and the referrals, conversions, and earnings that follow — back to the campaign that produced them, so each placement's performance can be measured independently. (The dashboard still labels these "In-email Campaigns".)

Every campaign has a `type` that determines what it points at: `recommendations_hub`, `specific_recommendation`, `offers_hub`, or `specific_offer`. The two hub types point at the whole hub and have no specific target.

### List campaigns

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

Paginated.

**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`. `target` cannot be expanded on the list — only on a single campaign. |
| from   | String | Start date (`YYYY-MM-DD`) for `stats`.                                        |
| to     | String | End date (`YYYY-MM-DD`) for `stats`.                                          |

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

```json
{
  "campaigns": [
    <Campaign Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 1,
    "total_campaigns": 6
  }
}
```

{% endtab %}

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

```json
{
  "error": "`target` can only be expanded on a single campaign."
}
```

{% endtab %}
{% endtabs %}

### Get campaign

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/tools/campaigns/: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 campaign's UUID.    |

**Query Parameters**

| Name   | Type   | Description                                                                |
| ------ | ------ | -------------------------------------------------------------------------- |
| expand | String | `target` (the recommendation or joined offer the link points at), `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
{
  "campaign": <Campaign Object>
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

### Create campaign

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

Creates a trackable campaign link. Hub types (`recommendations_hub`, `offers_hub`) need no target UUID. Specific types resolve a publication-scoped recommendation or joined offer by UUID.

**Path Parameters**

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

**Body Parameters**

| Name                                             | Type   | Description                                                                                                                              |
| ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| campaign\_type<mark style="color:red;">\*</mark> | String | `recommendations_hub`, `specific_recommendation`, `offers_hub`, or `specific_offer`. Invalid → `400`.                                    |
| name                                             | String | Campaign name. Required for hub types. Optional for specific types — defaults to `"<target> - <date>"` (same as the dashboard new form). |
| recommendation\_uuid                             | String | Joined recommendation UUID. Used when `campaign_type` is `specific_recommendation` (404 if unknown; 422 if missing).                     |
| offer\_recommendation\_uuid                      | String | Joined earn-offer UUID. Used when `campaign_type` is `specific_offer` (404 if unknown; 422 if missing).                                  |

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

```json
{
  "campaign": <Campaign Object>
}
```

{% endtab %}

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

```json
{
  "error": "`campaign_type` is required."
}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
  "error": "Please select a recommendation"
}
```

{% endtab %}
{% endtabs %}