# Campaigns

Organize attribution around a partner campaign.



[Authentication](/build/authentication/) · [Errors](/build/errors/) · [Amounts and units](/build/units/)


Response examples below come from a local test account. IDs, balances and timestamps are sample data. Replace IDs and credentials with values from your account.


## Create campaign for partner

`POST /partners/{id}/campaigns`


**Access:** `partner:admin`.


**SDK methods:** TypeScript `client.campaigns.create(…)`; Python `client.campaigns.create(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes |  |


### Request body

Schema: [CreateCampaignInputDto](/api/partner-models/#createcampaigninputdto)


### Request example

```bash
curl --fail-with-body -X POST "$THESAUROS_API_BASE/partners/ptn_seed_acme/campaigns" \
  -H "Authorization: Bearer $THESAUROS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Earn pilot"}'
```

### Response · 201

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [CampaignOutputDto](/api/partner-models/#campaignoutputdto) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "campaign",
  "data": {
    "id": "cmp_a4dc6e7ca61e7b0c",
    "object": "campaign",
    "partner_id": "ptn_seed_acme",
    "name": "Earn pilot",
    "slug": "earn-pilot",
    "utm_source": null,
    "utm_medium": null,
    "status": "active",
    "created_at": "2026-09-07T14:42:44.147Z",
    "updated_at": "2026-09-07T14:42:44.147Z"
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## List campaigns for partner

`GET /partners/{id}/campaigns`


**Access:** `partner:admin`.


**SDK methods:** TypeScript `client.campaigns.list(…)`; Python `client.campaigns.list(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes |  |

| `status` | query | `"active"`, `"disabled"` | No |  |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/partners/ptn_seed_acme/campaigns" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [CampaignOutputDto](/api/partner-models/#campaignoutputdto)[] | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "list",
  "data": [
    {
      "id": "cmp_seed_acme_launch",
      "object": "campaign",
      "partner_id": "ptn_seed_acme",
      "name": "Acme Summer Launch",
      "slug": "summer-launch",
      "utm_source": "twitter",
      "utm_medium": "cpc",
      "status": "active",
      "created_at": "2026-06-03T12:00:00.000Z",
      "updated_at": "2026-07-18T12:00:00.000Z"
    },
    {
      "id": "cmp_seed_acme_earn",
      "object": "campaign",
      "partner_id": "ptn_seed_acme",
      "name": "Acme Earn Widget",
      "slug": "earn-widget",
      "utm_source": "widget",
      "utm_medium": "embed",
      "status": "active",
      "created_at": "2026-06-18T12:00:00.000Z",
      "updated_at": "2026-07-25T12:00:00.000Z"
    },
    {
      "id": "cmp_a4dc6e7ca61e7b0c",
      "object": "campaign",
      "partner_id": "ptn_seed_acme",
      "name": "Earn pilot",
      "slug": "earn-pilot",
      "utm_source": null,
      "utm_medium": null,
      "status": "active",
      "created_at": "2026-09-07T14:42:44.147Z",
      "updated_at": "2026-09-07T14:42:44.147Z"
    }
  ]
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Update campaign

`PATCH /partners/{id}/campaigns/{campaignId}`


Partial update. Pass status:"disabled" to soft-disable a campaign without deleting it.


**Access:** `partner:admin`.


**SDK methods:** TypeScript `client.campaigns.update(…)`; Python `client.campaigns.update(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes |  |

| `campaignId` | path | `string` | Yes |  |


### Request body

Schema: [UpdateCampaignInputDto](/api/partner-models/#updatecampaigninputdto)


### Request example

```bash
curl --fail-with-body -X PATCH "$THESAUROS_API_BASE/partners/ptn_seed_acme/campaigns/cmp_a4dc6e7ca61e7b0c" \
  -H "Authorization: Bearer $THESAUROS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Earn pilot phase two"}'
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [CampaignOutputDto](/api/partner-models/#campaignoutputdto) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "campaign",
  "data": {
    "id": "cmp_a4dc6e7ca61e7b0c",
    "object": "campaign",
    "partner_id": "ptn_seed_acme",
    "name": "Earn pilot phase two",
    "slug": "earn-pilot",
    "utm_source": null,
    "utm_medium": null,
    "status": "active",
    "created_at": "2026-09-07T14:42:44.147Z",
    "updated_at": "2026-09-07T14:42:44.288Z"
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).