> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Werbekampagnen

> Erstellen, lesen und aktualisieren Sie Werbekampagnen, denen kein Beitrag zugrunde liegt, etwa Suchkampagnen.

Eine Kampagne ist eine Anzeige, die nicht von einem Ihrer Beiträge ausgeht. Verwenden Sie sie für Formate wie Suchanzeigen, bei denen Sie ein Budget, eine Gebotsstrategie und das Targeting festlegen und das Netzwerk die Anzeigen erstellt.

Um einen bereits veröffentlichten Beitrag zu bewerben, verwenden Sie stattdessen [Beitrag bewerben](https://www.ayrshare.com/docs/apis/ads/facebook/boost-post.md).

> [!NOTE]
>
> Google akzeptiert Kampagnen. Was speziell für Google gilt, steht unter [Google-Suchkampagnen](https://www.ayrshare.com/docs/apis/ads/google/search-campaigns.md) und [Google Performance Max-Kampagnen](https://www.ayrshare.com/docs/apis/ads/google/performance-max-campaigns.md). Andere Netzwerke lehnen eine Kampagnenanfrage mit `code: 101` ab, und `details` nennt den Grund. Bei Facebook lautet die Meldung beispielsweise `campaignCreation is not supported on facebook.`

## Endpunkte

| Methode | Pfad | Funktion |
| - | - | - |
| `POST` | `/ads/{platform}/campaigns` | Eine Kampagne erstellen |
| `GET` | `/ads/{platform}/campaigns/{id}` | Eine Kampagne abrufen |
| `PUT` | `/ads/{platform}/campaigns/{id}` | Eine Kampagne ändern |

`{platform}` ist das Werbenetzwerk. `{id}` ist die Kampagnen-ID, die beim Erstellen zurückgegeben wurde. Sie können nur Kampagnen lesen und ändern, die über Ayrshare vom selben Benutzerprofil erstellt wurden.

## Header-Parameter

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

**Idempotency-Key** `string` *required*

Erforderlich, um eine Kampagne zu erstellen. Senden Sie für jede neue Kampagne einen neuen eindeutigen Wert, etwa eine UUID. Wenn Sie eine Anfrage mit demselben Schlüssel wiederholen, gibt Ayrshare die erste Antwort zurück, gekennzeichnet mit `idempotentReplayed: true`, und erstellt nichts Neues. Sie können den Schlüssel stattdessen auch im Body als `idempotencyKey` senden. Wenn Sie beide senden, müssen sie übereinstimmen.

## Eine Kampagne erstellen

`POST /ads/{platform}/campaigns`

Neue Kampagnen starten mit `paused`, sofern Sie nicht `status: "active"` senden. So wird kein Geld ausgegeben, bis Sie den Start selbst veranlassen.

**accountId** `string` *required*

Das Werbekonto, in dem die Kampagne erstellt werden soll.

**name** `string` *required*

Der Kampagnenname, 1 bis 255 Zeichen.

**type** `string` *required*

Der Kampagnentyp: `search` oder `performanceMax`. Jedes Netzwerk unterstützt nur einige Typen. Ein Typ, den das Netzwerk nicht unterstützt, gibt `code: 101` zurück und listet die unterstützten Typen auf.

**budget** `object` *required*

**Eigenschaften**

**amount** `number` *required*

Wie viel pro Tag ausgegeben werden soll, mit höchstens zwei Dezimalstellen.

**type** `string` *required*

`daily`.

**currency** `string`

ISO 4217-Code, etwa `USD`. Standardmäßig die Währung des Werbekontos. Nur einige Netzwerke akzeptieren diesen Wert.

**bidding** `object` *required*

**Eigenschaften**

**strategy** `string` *required*

`maximizeConversions`, `maximizeConversionValue`, `targetCpa`, `targetRoas`, `maximizeClicks` oder `manualCpc`. Jedes Netzwerk unterstützt nur einige Strategien.

**targetCpa** `number`

Ziel-Kosten pro Aktion. Erforderlich bei `targetCpa` und bei keiner anderen Strategie zulässig.

**targetRoas** `number`

Ziel-Rendite der Werbeausgaben, zum Beispiel `3.5` für 350 %. Erforderlich bei `targetRoas` und bei keiner anderen Strategie zulässig.

**euPoliticalAdvertising** `boolean` *required*

Gibt an, ob es sich bei der Kampagne um politische Werbung in der EU handelt. Sie müssen diesen Wert immer senden. Ayrshare füllt ihn niemals für Sie aus.

**schedule** `object`

**Eigenschaften**

**start** `string`

Wann gestartet werden soll: ein ISO-Datum (`2026-11-01`) oder eine ISO-Datums- und Uhrzeitangabe mit `Z` oder einem Offset (`2026-11-01T09:00:00Z`). Standardmäßig jetzt.

**end** `string`

Wann beendet werden soll, im selben Format wie `start`. Muss nach `start` liegen bzw. nach dem aktuellen Zeitpunkt, wenn Sie `start` weglassen. Lassen Sie den Wert weg, damit die Kampagne ohne Enddatum läuft. Ein Netzwerk, das ganze Tage plant, wie Google, akzeptiert für eine eintägige Kampagne auch ein `end` am selben Tag wie `start`.

**targeting** `object`

Jedes Netzwerk unterstützt nur einen Teil des Targetings. Ein Feld, das das Netzwerk nicht unterstützt, gibt `code: 101` zurück.

**Eigenschaften**

**locations** `string[]`

Die netzwerkeigenen Standort-IDs.

**languages** `string[]`

Die netzwerkeigenen Sprach-IDs.

**status** `string` (default: paused)

`active` oder `paused`.

**platformOptions** `object`

Optionen nur für ein Netzwerk, unter dem Namen dieses Netzwerks, zum Beispiel `{ "facebook": { ... } }`. Optionen für jedes andere Netzwerk geben `code: 101` zurück.

```bash cURL theme={"system"}
curl \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10" \
-X POST https://api.ayrshare.com/api/ads/google/campaigns \
-d '{
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}'
```

```javascript JavaScript theme={"system"}
const API_KEY = "API_KEY";

fetch("https://api.ayrshare.com/api/ads/google/campaigns", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10"
  },
  body: JSON.stringify({
    "accountId": "123-456-7890",
    "name": "Spring search",
    "type": "search",
    "budget": { "amount": 20, "type": "daily" },
    "bidding": { "strategy": "maximizeClicks" },
    "euPoliticalAdvertising": false,
    "platformOptions": {
      "google": {
        "finalUrl": "https://example.com/spring",
        "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
        "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
        "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
      }
    }
  })
})
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch(console.error);
```

```python Python theme={"system"}
import requests

headers = {
    "Authorization": "Bearer API_KEY",
    "Idempotency-Key": "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10",
}

payload = {
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": False,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}

r = requests.post("https://api.ayrshare.com/api/ads/google/campaigns", headers=headers, json=payload)

print(r.json())
```

```php PHP theme={"system"}
<?php
$payload = <<<'JSON'
{
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}
JSON;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.ayrshare.com/api/ads/google/campaigns",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10"
    ],
    CURLOPT_POSTFIELDS => $payload
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error: " . $err;
} else {
    echo $response;
}
?>
```

```csharp C# theme={"system"}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");
        client.DefaultRequestHeaders.Add("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10");

        var payload = """
            {
              "accountId": "123-456-7890",
              "name": "Spring search",
              "type": "search",
              "budget": { "amount": 20, "type": "daily" },
              "bidding": { "strategy": "maximizeClicks" },
              "euPoliticalAdvertising": false,
              "platformOptions": {
                "google": {
                  "finalUrl": "https://example.com/spring",
                  "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
                  "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
                  "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
                }
              }
            }
            """;

        var response = await client.PostAsync(
            "https://api.ayrshare.com/api/ads/google/campaigns",
            new StringContent(payload, Encoding.UTF8, "application/json"));
        var content = await response.Content.ReadAsStringAsync();

        Console.WriteLine(content);
    }
}
```

```go Go theme={"system"}
package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    payload := `{
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}`

    req, _ := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/google/campaigns", strings.NewReader(payload))
    req.Header.Add("Authorization", "Bearer API_KEY")
    req.Header.Add("Content-Type", "application/json")
    req.Header.Add("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```java Java theme={"system"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CreateCampaign {
    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "accountId": "123-456-7890",
              "name": "Spring search",
              "type": "search",
              "budget": { "amount": 20, "type": "daily" },
              "bidding": { "strategy": "maximizeClicks" },
              "euPoliticalAdvertising": false,
              "platformOptions": {
                "google": {
                  "finalUrl": "https://example.com/spring",
                  "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
                  "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
                  "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
                }
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.ayrshare.com/api/ads/google/campaigns"))
            .header("Authorization", "Bearer API_KEY")
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

```ruby Ruby theme={"system"}
require 'net/http'
require 'uri'

uri = URI.parse('https://api.ayrshare.com/api/ads/google/campaigns')

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer API_KEY'
request['Content-Type'] = 'application/json'
request['Idempotency-Key'] = '6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10'
request.body = <<~JSON
  {
    "accountId": "123-456-7890",
    "name": "Spring search",
    "type": "search",
    "budget": { "amount": 20, "type": "daily" },
    "bidding": { "strategy": "maximizeClicks" },
    "euPoliticalAdvertising": false,
    "platformOptions": {
      "google": {
        "finalUrl": "https://example.com/spring",
        "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
        "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
        "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
      }
    }
  }
JSON

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body
```

Eine erfolgreiche Erstellung gibt `status: "success"`, die `campaignId` und den eigenen Status der Kampagne als `campaignStatus` (`active` oder `paused`) zurück. Abrufen und Aktualisieren antworten auf dieselbe Weise.

## Eine Kampagne abrufen

`GET /ads/{platform}/campaigns/{id}`

Gibt die Kampagne so zurück, wie das Netzwerk sie meldet. Eine Kampagne, die nicht Ihnen gehört oder nicht existiert, gibt `code: 400` zurück.

## Eine Kampagne aktualisieren

`PUT /ads/{platform}/campaigns/{id}`

Senden Sie mindestens eines dieser Felder. `type`, `accountId` und `euPoliticalAdvertising` können Sie nach dem Erstellen der Kampagne nicht mehr ändern.

**name** `string`

Der neue Kampagnenname.

**status** `string`

`active` oder `paused`. Eine Anfrage, die nur `status: "paused"` sendet, wird nicht blockiert, wenn Ayrshare Anzeigen in diesem Netzwerk pausiert hat. Sie erfordert dennoch ein verknüpftes Netzwerk und kann weiterhin fehlschlagen, wenn das Netzwerk selbst nicht erreichbar ist.

**budget** `object`

`{ "amount": number }`: der neue Betrag, der pro Tag ausgegeben werden soll.

**schedule** `object`

`{ "end": string }`: das neue Enddatum, im selben Format wie `schedule.start`. Es muss nach dem Start der Kampagne liegen. Ein Netzwerk, das ganze Tage plant, wie Google, akzeptiert auch denselben Tag wie den Start.

## Fehler

Diese Fehler enthalten einen Ayrshare-`code`:

| Code | Wann |
| - | - |
| `101` | Die Anfrage ist ungültig, das Netzwerk unterstützt keine Kampagnen oder diesen Kampagnentyp, oder der Idempotenzschlüssel fehlt. `details` gibt an, was zutrifft. Ayrshare prüft den Schlüssel erst, nachdem bestätigt wurde, dass das Netzwerk verknüpft ist. Ein nicht verknüpftes Profil erhält daher zuerst den Fehler "not linked" (nicht verknüpft). |
| `400` | Die Kampagne gehört nicht Ihnen oder existiert nicht. |
| `424` | Anzeigen in diesem Netzwerk sind vorübergehend nicht verfügbar. |

Eine Erstellung kann auch mit einem dieser HTTP-Status antworten. Der Body enthält dann keinen `code`, sondern nur `{ "action": "createAdCampaign", "status": "error", "message": "..." }`:

| HTTP-Status | Wann |
| - | - |
| `409` | Der Idempotenzschlüssel wurde mit einer anderen Anfrage verwendet, oder die Anfrage mit diesem Schlüssel wird noch verarbeitet. Wiederholen Sie die Anfrage nicht mit einem neuen Schlüssel. Prüfen Sie zuerst das Werbekonto. |
| `503` | Ayrshare konnte den Idempotenzschlüssel nicht sicher reservieren, daher wurde nichts erstellt. Versuchen Sie es später mit demselben Schlüssel erneut. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.