> ## 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.

# Campagnes publicitaires

> Créez, consultez et modifiez des campagnes publicitaires qui ne reposent sur aucune publication, comme les campagnes sur le Réseau de Recherche.

Une campagne est une annonce qui ne part pas de l'une de vos publications. Utilisez-la pour des formats comme les annonces sur le Réseau de Recherche, pour lesquels vous définissez un budget, une stratégie d'enchères et un ciblage, et le réseau crée les annonces.

Pour promouvoir une publication déjà publiée, utilisez plutôt [Sponsoriser une publication](https://www.ayrshare.com/docs/apis/ads/facebook/boost-post.md).

> [!NOTE]
>
> Google accepte les campagnes. Consultez [Campagnes sur le Réseau de Recherche Google](https://www.ayrshare.com/docs/apis/ads/google/search-campaigns.md) et [Campagnes Google Performance Max](https://www.ayrshare.com/docs/apis/ads/google/performance-max-campaigns.md) pour ce qui est propre à Google. Les autres réseaux refusent une requête de campagne avec `code: 101`, et `details` en indique la raison. Sur Facebook, par exemple, le message est `campaignCreation is not supported on facebook.`

## Endpoints

| Méthode | Chemin | Rôle |
| - | - | - |
| `POST` | `/ads/{platform}/campaigns` | Créer une campagne |
| `GET` | `/ads/{platform}/campaigns/{id}` | Obtenir une campagne |
| `PUT` | `/ads/{platform}/campaigns/{id}` | Modifier une campagne |

`{platform}` est le réseau publicitaire. `{id}` est l'ID de campagne renvoyé lors de sa création. Vous ne pouvez consulter et modifier que les campagnes créées via Ayrshare par le même profil utilisateur.

## Paramètres d'en-tête

**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*

Obligatoire pour créer une campagne. Envoyez une nouvelle valeur unique, comme un UUID, pour chaque nouvelle campagne. Si vous répétez une requête avec la même clé, Ayrshare renvoie la première réponse, marquée `idempotentReplayed: true`, et ne crée rien de nouveau. Vous pouvez aussi envoyer la clé dans le corps sous la forme `idempotencyKey`. Si vous envoyez les deux, elles doivent correspondre.

## Créer une campagne

`POST /ads/{platform}/campaigns`

Les nouvelles campagnes démarrent en `paused` sauf si vous envoyez `status: "active"`, afin que rien ne soit dépensé tant que vous n'avez pas décidé de les lancer.

**accountId** `string` *required*

Le compte publicitaire dans lequel créer la campagne.

**name** `string` *required*

Le nom de la campagne, de 1 à 255 caractères.

**type** `string` *required*

Le type de campagne : `search` ou `performanceMax`. Chaque réseau ne prend en charge que certains types. Un type non pris en charge par le réseau renvoie `code: 101` et liste les types pris en charge.

**budget** `object` *required*

**propriétés**

**amount** `number` *required*

Le montant à dépenser par jour, avec au plus deux décimales.

**type** `string` *required*

`daily`.

**currency** `string`

Code ISO 4217, comme `USD`. Par défaut, la devise du compte publicitaire. Seuls certains réseaux l'acceptent.

**bidding** `object` *required*

**propriétés**

**strategy** `string` *required*

`maximizeConversions`, `maximizeConversionValue`, `targetCpa`, `targetRoas`, `maximizeClicks` ou `manualCpc`. Chaque réseau ne prend en charge que certaines stratégies.

**targetCpa** `number`

Coût par action cible. Obligatoire avec `targetCpa`, et refusé avec toute autre stratégie.

**targetRoas** `number`

Retour sur les dépenses publicitaires cible, par exemple `3.5` pour 350 %. Obligatoire avec `targetRoas`, et refusé avec toute autre stratégie.

**euPoliticalAdvertising** `boolean` *required*

Indique si la campagne constitue de la publicité politique dans l'UE. Vous devez toujours l'envoyer. Ayrshare ne le renseigne jamais à votre place.

**schedule** `object`

**propriétés**

**start** `string`

Date de début : une date ISO (`2026-11-01`) ou une date-heure ISO avec `Z` ou un décalage (`2026-11-01T09:00:00Z`). Par défaut, maintenant.

**end** `string`

Date de fin, au même format que `start`. Doit être postérieure à `start`, ou à maintenant si vous omettez `start`. Omettez-la pour une diffusion sans date de fin. Un réseau qui planifie des journées entières, comme Google, accepte aussi un `end` le même jour que `start`, pour une campagne d'une seule journée.

**targeting** `object`

Chaque réseau ne prend en charge qu'une partie du ciblage. Un champ non pris en charge par le réseau renvoie `code: 101`.

**propriétés**

**locations** `string[]`

Les ID de lieux propres au réseau.

**languages** `string[]`

Les ID de langues propres au réseau.

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

`active` ou `paused`.

**platformOptions** `object`

Options propres à un seul réseau, sous le nom de ce réseau, par exemple `{ "facebook": { ... } }`. Les options destinées à tout autre réseau renvoient `code: 101`.

```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
```

Une création réussie renvoie `status: "success"`, le `campaignId` et l'état propre de la campagne dans `campaignStatus` (`active` ou `paused`). La consultation et la modification répondent de la même manière.

## Obtenir une campagne

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

Renvoie la campagne telle que le réseau la rapporte. Une campagne qui ne vous appartient pas, ou qui n'existe pas, renvoie `code: 400`.

## Modifier une campagne

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

Envoyez au moins l'un de ces champs. Vous ne pouvez pas modifier `type`, `accountId` ou `euPoliticalAdvertising` après la création de la campagne.

**name** `string`

Le nouveau nom de la campagne.

**status** `string`

`active` ou `paused`. Une requête qui envoie uniquement `status: "paused"` n'est pas bloquée lorsque Ayrshare a mis en pause les annonces sur ce réseau. Elle nécessite tout de même un réseau lié, et peut encore échouer si le réseau lui-même est indisponible.

**budget** `object`

`{ "amount": number }` : le nouveau montant à dépenser par jour.

**schedule** `object`

`{ "end": string }` : la nouvelle date de fin, au même format que `schedule.start`. Elle doit être postérieure au début de la campagne. Un réseau qui planifie des journées entières, comme Google, accepte aussi le même jour que le début.

## Erreurs

Ces erreurs comportent un `code` Ayrshare :

| Code | Quand |
| - | - |
| `101` | La requête est invalide, le réseau ne prend pas en charge les campagnes ou ce type de campagne, ou la clé d'idempotence est manquante. `details` précise le cas. Ayrshare vérifie la clé après avoir confirmé que le réseau est lié, donc un profil non lié reçoit d'abord l'erreur "not linked" (non lié). |
| `400` | La campagne ne vous appartient pas ou n'existe pas. |
| `424` | Les annonces sur ce réseau sont temporairement indisponibles. |

Une création peut aussi renvoyer l'un de ces statuts HTTP. Son corps ne contient pas de `code`, seulement `{ "action": "createAdCampaign", "status": "error", "message": "..." }` :

| Statut HTTP | Quand |
| - | - |
| `409` | La clé d'idempotence a été utilisée avec une requête différente, ou la requête associée à cette clé est toujours en cours. Ne réessayez pas avec une nouvelle clé. Vérifiez d'abord le compte publicitaire. |
| `503` | Ayrshare n'a pas pu réserver la clé d'idempotence en toute sécurité, donc rien n'a été créé. Réessayez plus tard avec la même clé. |


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