V2 (latest)

Overview

The Decision API is a RESTful API that serves as the engine behind Flagship. It is published on Amazon API Gateway and distributed in eight regions with collocated AWS Lambda and DynamoDB Global Tables to deliver exceptional performance across the globe.

You can access the Decision API endpoints to trigger visitor assignments according to the targeting criteria you define in the Flagship dashboard and receive responses with flag, campaign, and variation details.

Implementing the Decision API directly in your application lets you and your team fine-tune each call and digest every response without any additional layers between Flagship and your applications.

The Decision API is language-agnostic by design, meaning you can use Flagship even if your stack includes a variety of programming languages, or if you would like to experiment with more specialized languages or frameworks for which we don't yet offer a dedicated SDK.

If you'd rather use an SDK with preconfigured methods to implement the Decision API, you can see the full list of available languages and learn more about SDK-specific features here.

We have language bindings in Shell (Curl) and Javascript (ES6). You can toggle between programming languages by using the tabs above each code example.

Feel free to contact us if you have any questions regarding this documentation.

📘

Early Adopter Program

The Early Adopter Program for the Decision API v2 has ended. If you still want to be an Early Adopter and benefits from every feature earlier, please contact us!

Authentication

Decision API resources are authenticated with an API key. This version of the Decision API requires the API Key to be sent in the following HTTP header:

x-api-key: YOUR_API_KEY

You can access your API Key in the Flagship Platform, inside Parameters / Environment & Security

📘

API throttling

The API endpoint /campaigns is limited to a certain amount of calls:

  • 200req/s with a temporary burst of 600req/s

If you were to have more call than planned, you will received a 429 error, enabling the default behavior for your users.

Want a higher limitation? Nothing is impossible 😉 Contact your dedicated account manager or our support.

Campaign assignment

Run all campaign assignments

This endpoint retrieves all the campaigns that correspond to the specified user and context attributes.

By default, the API will send a CAMPAIGN hit to Flagship for each campaign in the response to notify the report that the visitor_id has been assigned to it.

const response = await axios.post(
  "https://decision.flagship.io/v2/<ENVIRONMENT_ID>/campaigns",
  {
    visitor_id: "YOUR_VISITOR_ID",
    context: {
      "YOUR KEY": "YOUR VALUE",
    },
    decision_group: null,
  },
  {
    headers: { "x-api-key": "YOUR_API_KEY" },
  }
);
curl -X POST \
  https://decision.flagship.io/v2/<ENVIRONMENT_ID>/campaigns \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
        "visitor_id": "YOUR_VISITOR_ID",
        "context": {
            "YOUR KEY": "YOUR VALUE"
        },
        "decision_group": null
    }'

The above command returns JSON structured as follows:

{
  "visitorId": "YOUR_VISITOR_ID",
  "campaigns": [
    {
      "id": "<CAMPAIGN_ID>",
      "variationGroupId": "<VARIATION_GROUP_ID>",
      "variation": {
        "id": "<VARIATION_ID>",
        "modifications": {
          "type": "JSON",
          "value": {
            "key": "value"
          }
        }
      }
    }
  ]
}

HTTP Request

POST https://decision.flagship.io/v2/<ENVIRONMENT_ID>/campaigns

Route Parameters

Parameter

Required

Default

Description

ENVIRONMENT_ID

yes

Identifies your account and environment (preprod or prod). Check your Flagship dashboard to find this ID.

Query Parameters

Parameter

Required

Default

Description

mode

no

normal

Specifies the format of the response body used by Flagship to return your campaign information. See description

Body Parameters

ParameterTypeRequiredDefaultDescription
visitor_idstringyesUnique identifier for the application user or website visitor. This can be an ID from your database or a session ID. Learn more
anonymous_idstringnoemptyIdentifier for the application user or website visitor when the visitor is anonymous. This can be a session ID for instance. Learn more
contextobjectnoemptyJSON object of key-value pairs describing the user and device context. Learn more
trigger_hitbooleannotrueDetermines whether a CAMPAIGN hit should be automatically sent to Flagship for each campaign targeting the user. Learn more
decision_groupstringnoemptyIf specified, users that match the targeting will be affected to a unique variation ID per decision group. See description

📘

The visitor_id should be a unique identifier for your application user or website visitor. Using a consistent visitor_id is what guarantees that a visitor will see the same variation of a campaign across sessions and clients.

Response Parameters

This API endpoint returns a Campaign response JSON object. See campaign response model

ParametertypeDescription
visitorIdstringThe visitor ID as you sent it in the request (only if mode=normal or mode=full).
campaignsarrayAn array of all the campaigns to which the user is assigned (only if mode=normal or mode=full). See Campaign response model
campaignsVariationarrayAn array of campaign IDs and the assigned variation ID (only if mode=simple or mode=full). See Campaign Variation response model
mergedModificationsobjectA key-value object of all the merged modifications of the campaign (only if mode=simple or mode=full).

Run a single campaign assignment

This endpoint retrieves the assignment of your visitor ID with a specific context (key-value pairs) to the specified campaign ID.

By default, the API will send a CAMPAIGN hit to Flagship for each campaign in the response to trigger campaign assignment events for the visitor_id.

const response = await axios.post(
  "https://decision.flagship.io/v2/<ENVIRONMENT_ID>/campaigns/<CAMPAIGN_ID>",
  {
    visitor_id: "YOUR_VISITOR_ID",
    context: {
      "YOUR KEY": "YOUR VALUE",
    },
    // Optional: see #decision-groups for details
    decision_group: null,
  },
  {
    headers: { "x-api-key": "YOUR_API_KEY" },
  }
);
curl -X POST \
  https://decision.flagship.io/v2/<ENVIRONMENT_ID>/campaigns/<CAMPAIGN_ID> \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
        "visitor_id": "YOUR_VISITOR_ID",
        "context": {
            "YOUR KEY": "YOUR VALUE"
        },
        // Optional: see #decision-groups for details
        "decision_group": null
    }'

The above command returns JSON structured like this:

{
  "id": "<CAMPAIGN_ID>",
  "variationGroupId": "<VARIATION_GROUP_ID>",
  "variation": {
    "id": "<VARIATION_ID>",
    "modifications": {
      "type": "JSON",
      "value": {
        "key": "value"
      }
    }
  }
}

HTTP Request

POST https://decision.flagship.io/v2/<ENVIRONMENT_ID>/campaigns/<CAMPAIGN_ID>

You can also use a GET request and pass all the body parameters as query parameters with the same format.

GET https://decision.flagship.io/v2/<ENVIRONMENT_ID>/campaigns/<CAMPAIGN_ID>?visitor_id=<visitor_id>&trigger_hit=<trigger_hit>&format_response=<format_response>&context=<context>&default_redirect_url=<default_redirect_url>

An example use case for this would be to include a campaign with a REDIRECT modification type in an email newsletter.

Query Parameters

ParameterRequiredDefaultDescription
ENVIRONMENT_IDyesIdentifies your account and environment (preprod or prod). Check your Flagship dashboard to find this ID.
CAMPAIGN_IDyesIdentifies the campaign for which you want to check the user's assignment. You can use Flagship generated campaign ID or the slug you specified for your campaign.

Body Parameters

ParameterTypeRequiredDefaultDescription
visitor_idstringyesUnique identifier for the application user or website visitor. This can be an ID from your database or a session ID. Learn more
anonymous_idstringnoemptyIdentifier for the application user or website visitor when the visitor is anonymous. This can be a session ID for instance. Learn more
contextobjectnoemptyJSON object of key-value pairs describing the user and device context. Learn more
decision_groupstringnoemptyIf specified, users that match the targeting will be affected to a unique variation ID per decision group. See description
format_responseboolnofalseIf set to true, the response of the API call will be formatted according to your modification type. See formatted response
default_redirect_urlstringnoemptyIf specified, the API call will always return a 302 redirect, with the modification redirection if defined, or the default_redirect_url if not defined

📘

The visitor_id should be a unique identifier for your application user or website visitor. Using a consistent visitor_id is what guarantees that a visitor will see the same variation of a campaign across sessions and clients.

See Experience Continuity to provide consistency between the anonymous & logged in state of your visitor.

Response Parameters

This API endpoint returns a Campaign response JSON object. See campaign response model

Experience Continuity

In some situations, you may want experience consistency between an anonymous visitor and an authenticated visitor.
Flagship provides a specific body parameter to specify the anonymous ID and differentiate it from the authenticated ID.

Anonymous visitor

When you visitor is considered anonymous (their ID is of type session ID), you can use the visitor_id field alone. The Decision API will see your visitor as anonymous.
Their experience will be consistent as long as they remain anonymous.

Code sample

curl -X POST \
  https://decision.flagship.io/v2/<ENVIRONMENT_ID>/campaigns \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
        "visitor_id": "{session_id}",
        "context": {
            "YOUR KEY": "YOUR VALUE"
        },
        "decision_group": null
    }'

Authenticated visitor

Once your visitor has been authenticated and has an authenticated ID (Database ID, profile ID, ...), you call call the Decision API again and change the visitor_id in the body from the session ID to the authenticated ID.

But in order for the experience to remain the same between anonymous and authenticated, you need to inform the Decision API about the previous anonymous ID of this user.

To to that, you need to fill the anonymous_id body parameter. The API will internally link the 2 IDs & keep the experience the same.

Code sample

curl -X POST \
  https://decision.flagship.io/v2/<ENVIRONMENT_ID>/campaigns \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
        "visitor_id": "{new_authenticated_id}",
        "anonymous_id": "{session_id}",
        "context": {
            "YOUR KEY": "YOUR VALUE"
        },
        "decision_group": null
    }'

Campaign activation

This endpoint assigns a user to a variation. It should be used to manually activate a single campaign and variation
in cases where you choose not to activate them automatically when running campaign assignment. See trigger_hit parameter

Example:

You create a campaign targeting visitors who are on the cart checkout screen of your mobile app.
At the initialization of your app, you want to get all campaigns and modifications associated with a user.

Since they are not on the basket screen yet, you don't want to assign the user to a variation at this stage. Instead, you would call this endpoint to assign the user to a variation only once they actually belong to the campaign.

const response = await axios.post("https://decision.flagship.io/v2/activate", {
  vid: "<YOUR_VISITOR_ID>",
  cid: "<ENVIRONMENT_ID>",
  caid: "<VARIATION_GROUP_ID>",
  vaid: "<VARIATION_ID>",
});
curl -X POST \
  "https://decision.flagship.io/v2/activate" \
  -H 'Content-Type: application/json' \
  -d '{
        "vid": "<YOUR_VISITOR_ID>",
        "cid": "<ENVIRONMENT_ID>",
        "caid": "<VARIATION_GROUP_ID>",
        "vaid": "<VARIATION_ID>"
    }'

The above request returns a 204: No Content HTTP response.

HTTP Request

POST https://decision.flagship.io/v2/activate

Body Parameters

ParameterTypeRequiredDefaultDescription
vidstringyesemptyUnique identifier for the application user or website visitor. This can be an ID from your database or a session ID. Learn more
cidstringyesemptyIdentifies your account and environment (preprod or prod). Check your Flagship dashboard to find this ID.
caidstringyesemptyCorresponds to the variationGroupID returned by the Decision API. Learn more
vaidstringyesemptyThe variation ID of which the user will be affected to. Learn more

Request parameters

Decision Group

The decision_group requests parameter enables your app to force the same variation assignment for a specific group of visitors.

Example:

  • You call the Decision API for a user with visitor_id=1, campaign_id=1, and decision_group=VIP_users. The assigned variationId will be selected randomly depending on the chosen traffic allocation) (e.g. variationId=1234).
  • You call the Decision API for a second user withvisitor_id=2, campaign_id=1, and the same decision_group=VIP_users. Because this user belongs to the same decision_group as the first, the API will assign them to the same variationId=1234 instead of a new random variation.

Trigger Hit

The trigger_hit parameter enables your code to automatically trigger the Universal Collect CAMPAIGN hit so that our reporting systems know that the visitor has seen the campaign.

🚧

The trigger_hit parameter is set to true by default unless you manually set it to false.

Mode

The mode query parameter allows you to change to format of the response in which the Decision API returns the campaign information:

Normal

mode=normal returns the visitorId and campaigns array with the full campaign information.

For mode=normal, the response body will have the following format:

{
  "visitorId": "YOUR_VISITOR_ID",
  "campaigns": [
    {
      "id": "<CAMPAIGN_ID>",
      "variationGroupId": "<VARIATION_GROUP_ID>",
      "variation": {
        "id": "<VARIATION_ID>",
        "modifications": {
          "type": "JSON",
          "value": {
            "key": "value"
          }
        }
      }
    }
  ]
}
Simple
  • mode=simple returns two elements:
    • a campaignsVariation array of campaignId and associated variationId for the visitor
    • a mergedModifications object containing all the remote values configured for the campaigns, merged into a single object

For mode=simple, the response body will have the following format:

{
  "campaignsVariation": [
    {
      "campaignId": "bk6d4m8r1p60038pr0t0",
      "variationId": "bk6d5dgr1p60071psgb0"
    },
    {
      "campaignId": "bkk5da8cmjcg07ee3sb0",
      "variationId": "bkk5da8cmjcg07ee3scg"
    }
  ],
  "mergedModifications": {
    "Test": true,
    "btn-color": "red",
    "my_text": "Welcome dude",
    "youpitext": "Hello"
  }
}
Full
  • mode=full returns all the elements for debugging purposes:
    • the visitorId
    • the campaigns array containing all the campaign information for this visitor
    • a campaignsVariation array of all campaignId and associated variationId values for the visitor
    • a mergedModifications object containing all the remote values configured for the campaigns, merged into a single object

For mode=full, the response body will have the following format:

{
  "visitorId": "visitor1234",
  "campaigns": [
    {
      "id": "bk6d4m8r1p60038pr0t0",
      "variationGroupId": "bk6d4m8r1p60038pr0u0",
      "variation": {
        "id": "bk6d5dgr1p60071psgb0",
        "modifications": {
          "type": "JSON",
          "value": {
            "btn-color": "red"
          }
        }
      }
    },
    {
      "id": "bkk5da8cmjcg07ee3sb0",
      "variationGroupId": "bkk5da8cmjcg07ee3sc0",
      "variation": {
        "id": "bkk5da8cmjcg07ee3scg",
        "modifications": {
          "type": "TEXT",
          "value": {
            "youpitext": "Hello AB Tasty!"
          }
        }
      }
    }
  ],
  "campaignsVariation": [
    {
      "campaignId": "bk6d4m8r1p60038pr0t0",
      "variationId": "bk6d5dgr1p60071psgb0"
    },
    {
      "campaignId": "bkk5da8cmjcg07ee3sb0",
      "variationId": "bkk5da8cmjcg07ee3scg"
    }
  ],
  "mergedModifications": {
    "Test": true,
    "btn-color": "red",
    "my_text": "Welcome, dude",
    "youpitext": "Hello"
  }
}

Response models

Campaign

Field nametypeDescription
visitorIdstringUnique identifier for the application user or website visitor. This can be an ID from your database or a session ID. Learn more
variationGroupIdstringCorresponds to a scenario in the Flagship dashboard)
variationobjectThe assigned variation information
variation.idstringThe affected variation ID
variation.modificationsobjectThe variation modifications information
variation.modifications.typestringThe modification type for the campaign (can be NULL, JSON, TEXT, IMAGE, HTML, FLAG, REDIRECT)
variation.modifications.valueobjectThe value of the modification

📘

The variation.modifications.value field can have the following structure, depending on the modification type:

  • type = 'JSON': value is a key-value pair of the JSON modification defined in the platform for the campaign
  • type = 'TEXT': value is an object with the structure {key:'text_key', value:'text_value'}
  • type = 'IMAGE': value is an object with the structure {key:'image_key', value:'image_value'}
  • type = 'HTML': value is an object with the structure {key:'html_key', value:'html_value'}
  • type = 'REDIRECT': value is an object with the structure {key:'redirect_key', value:'redirect_value'}
  • type = 'FLAG': value is an object with the structure {'flag_name': 'flag_value'}

Campaign Variation

Field nametypeDescription
campaignIdstringIdentifies the campaign
variationIdstringThe variation ID assigned to the user

Formatted campaign

If you set the format_response parameter to true in the campaign request, the Decision API will attempt to return HTTP-formatted content for your campaign modifications.

The formatted content depends on the campaign modification type configured in the Flagship dashboard:

Modification typeContent-TypeStatus CodeHTTP response body
JSONapplication/JSON200The JSON object defined for the campaign
TEXTtext/plain200The text defined for the campaign
HTMLtext/HTML200The HTML defined the campaign
IMAGEimage200The content of the image URL defined for the campaign
REDIRECTapplication/JSON302The key/value JSON object of the flags defined for the campaign
FLAGapplication/JSON200The key/value JSON object of the flags defined for the campaign

Reference

You can see the endpoints definitions and try them out using our Swagger UI page


Did this page help you?