Manage campaigns

With the Remote Control API, you can create, update or delete you campaigns but also the variations of itself. A campaign is an aggregation of variation groups, which are themselves an aggregation of variations. The campaign architecture is the following :

{
  "id": "c1",
  "name": "My campaign",
  "variation_groups": [
    {
      "id": "vg1",
      "name": "variation_group",
      "variations": [
        {
          "id": "v1",
          "name": "Variation 1"
        },
        {
          "id": "v2",
          "name": "Variation 2"
        }
      ]
    }
  ]
}

List your campaigns

👍 Required scope : campaign.list

curl --location --request GET 'https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns?_page=1' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Create a campaign

👍 Required scope : campaign.create

curl --location --request POST '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--data-raw '{BODY}'

Replace {BODY} with the following json :

{
    "project_id": "{PROJECT_ID}",
    "name": "New AB test",
    "description": "My new AB test",
    "type": "ab",
    "variation_groups": [
        {
            "name": "variation_group",
            "variations": [
                {
                    "name": "My variation 1",
                    "allocation": 50,
                    "reference": true,
                    "modifications": {
                        "value": {
                            "color": "blue"
                        }
                    }
                },
                {
                    "name": "My variation 2",
                    "allocation": 50,
                    "reference": false,
                    "modifications": {
                        "value": {
                            "color": "red"
                        }
                    }
                }
            ],
            "targeting": {
                "targeting_groups": [
                    {
                        "targetings": [
                            {
                                "operator": "CONTAINS",
                                "key": "isVIP",
                                "value": "true"
                            }
                        ]
                    }
                ]
            }
        }
    ],
    "scheduler": {
        "start_date": "2022-02-01 10:00:00",
        "stop_date": "2022-02-02 08:00:00",
        "timezone": "Europe/Paris"
    }
}

The previous example will create a campaign with type ab, with 2 variations returning the flag color red or blue. The targeting applied means that the context for the visitor should CONTAIN "isVIP" and its value must be "true".

Create a new variation group in a campaign

curl --location --request POST '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--data-raw '{BODY}'

Replace {BODY} with the same previous payload (variation_group part) :

Create a new variation in a variation group

curl --location --request POST '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups/{VARIATION_GROUP_ID}/variations' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--data-raw '{BODY}'

Replace {BODY} with the same previous payload (variation part) :

View a campaign

👍 Required scope : campaign.read

curl --location --request GET '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

View variation groups of a campaign

curl --location --request GET '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

View a specific variation group

curl --location --request GET '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups/{VARIATION_GROUP_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

View variations of a variation group

curl --location --request GET '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups/{VARIATION_GROUP_ID}/variations' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

View a specific variation

curl --location --request GET '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups/{VARIATION_GROUP_ID}/variations/{VARIATION_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Update a campaign

👍 Required scope : campaign.update

curl --location --request PATCH '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'
--data-raw '{BODY}'

As you prefer, you can use the global campaign routes to edit the children variations, variation_groups of your campaign or you can use the specific routes to updates them.

❗️ Be careful

If you use the global campaign route to edit variations or variation groups, you have to put in the payload the entire sub collection of it, and don't forget to add the parameter id to each child. If you don't do this, the entire sub-collection will be replaced and the old children will be erased or replaced.

To avoid this, when you need to update a specific item in the variations for example, prefer to use the direct route to edit one variation.

Update a specific variation group

curl --location --request PATCH '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups/{VARIATION_GROUP_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'
--data-raw '{BODY}'

Update a specific variation

curl --location --request PATCH '
https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups/{VARIATION_GROUP_ID}/variations/{VARIATION_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'
--data-raw '{BODY}'

Toggle a campaign

👍 Required scope : campaign.toggle

curl --location --request PATCH 'https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/toggle' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--data-raw '{
    "state": "active"
}'

📘 The different states are active , paused , interrupted .

Delete a campaign

👍 Required scope : campaign.delete

❗️ Be careful, there is no confirmation step when you call these routes. It will delete it definitively.

curl --location --request DELETE 'https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Delete a specific variation group

curl --location --request DELETE 'https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups/{VARIATION_GROUP_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Delete a specific variation

curl --location --request DELETE 'https://api.flagship.io/v1/accounts/{ACCOUNT_ID}/account_environments/{ACCOUNT_ENVIRONMENT_ID}/campaigns/{CAMPAIGN_ID}/variation_groups/{VARIATION_GROUP_ID}/variations/{VARIATION_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'