V1 (deprecated)
Overview
Decision API V1 Sunset
The Decision API v1 is entering in Sunset phase, the service will be fully discontinued on March 31th 2022 at 12PM UTC. After this date, the API v1 infrastructure will be shutdown and won’t be reachable anymore.
We kindly remind our customers to move forward as soon as possible to the next stable version of the API, Decision API V2.
Please note that bigger latency may occur, including instability, and no more support on the v1 will be delivered during the Sunset Phase
The Decision API is a RESTful API that serves as the engine behind Flagship.
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.
Feel free to contact us if you have any questions regarding this documentation.
We have language bindings in Shell (Curl) and Javascript (ES6). You can toggle between programming languages by using the tabs above each code example.
Authentication
Decision API resources are authenticated using the environment ID in the request URL:
POST https://decision-api.flagship.io/v1/<ENVIRONMENT_ID>/<ENDPOINT>
Check your Flagship dashboard to find your environment ID.
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 trigger campaign assignment events for the visitor_id
.
const response = await axios.post(
"https://decision-api.flagship.io/v1/<ENVIRONMENT_ID>/campaigns", {
visitor_id: "YOUR_VISITOR_ID",
context: {
"YOUR KEY": "YOUR VALUE",
},
decision_group: null,
});
curl -X POST \
${DecisionAPIURL(1)}/<ENVIRONMENT_ID>/campaigns \\
-H 'Content-Type: application/json' \\
-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-api.flagship.io/v1/<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
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
visitor_id | string | yes | Unique identifier for the application user or website visitor. This can be an ID from your database or a session ID. Learn more | |
trigger_hit | boolean | no | true | Determines whether a CAMPAIGN hit should be automatically sent to Flagship for each campaign targeting the user. Learn more |
context | object | no | empty | JSON object of key-value pairs describing the user and device context. Learn more |
decision_group | string | no | empty | If 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 consistentvisitor_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
Parameter | type | Description |
---|---|---|
visitorId | string | The visitor ID as you sent it in the request (only if mode=normal or mode=full ). |
campaigns | array | An array of all the campaigns to which the user is assigned (only if mode=normal or mode=full ). See Campaign response model |
campaignsVariation | array | An array of campaign IDs and the assigned variation ID (only if mode=simple or mode=full ). See Campaign Variation response model |
mergedModifications | object | A 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-api.flagship.io/v1/<ENVIRONMENT_ID>/campaigns/<CAMPAIGN_ID>",
{
visitor_id: "YOUR_VISITOR_ID",
context: {
"YOUR KEY": "YOUR VALUE",
},
// Optional : see #/decision_groups for details
decision_group: null,
}
);
curl -X POST \\
${DecisionAPIURL(1)}/<ENVIRONMENT_ID>/campaigns/<CAMPAIGN_ID> \\
-H 'Content-Type: application/json' \\
-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-api.flagship.io/v1/<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-api.flagship.io/v1/<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
Parameter | Required | Default | Description |
---|---|---|---|
ENVIRONMENT_ID | yes | Identifies your account and environment (preprod or prod). Check your Flagship dashboard to find this ID. | |
CAMPAIGN_ID | yes | Identifies the campaign to which you want to check the user's assignment |
Body Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
visitor_id | string | yes | Unique identifier for the application user or website visitor. This can be an ID from your database or a session ID. Learn more | |
context | object | no | empty | JSON object of key-value pairs describing the user and device context. Learn more |
decision_group | string | no | empty | If specified, users that match the targeting will be assigned to a unique variation ID per decision group. See description |
format_response | bool | no | false | If set to true, the response of the API call will be formatted according to your modification type. See formatted response |
default_redirect_url | string | no | empty | If 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 consistentvisitor_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
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 users who are on the basket 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-api.flagship.io/v1/activate", {
vid: "<YOUR_VISITOR_ID>",
cid: "<ENVIRONMENT_ID>",
caid: "<VARIATION_GROUP_ID>",
vaid: "<VARIATION_ID>",
});
curl -X POST \\
"${DecisionAPIURL(1)}/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-api.flagship.io/v1/activate
Body Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
vid | string | yes | empty | Unique identifier for the application user or website visitor. This can be an ID from your database or a session ID. Learn more |
cid | string | yes | empty | Identifies your account and environment (preprod or prod). Check your Flagship dashboard to find this ID. |
caid | string | yes | empty | Corresponds to the variationGroupID returned by the Decision API. (Learn more)[../docs/glossary.mdx#variation-group-id] |
vaid | string | yes | empty | The variation ID of which the user will be affected to. (Learn more)[../docs/glossary.mdx#variation-id] |
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
, anddecision_group=VIP_users
. The assignedvariationId
will be selected randomly depending on the chosen traffic allocation) (e.g.variationId=1234
). - You call the Decision API for a second user with
visitor_id=2
,campaign_id=1
, and the samedecision_group=VIP_users
. Because this user belongs to the samedecision_group
as the first, the API will assign them to the samevariationId=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 totrue
by default unless you manually set it tofalse
.
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 associatedvariationId
for the visitor - a
mergedModifications
object containing all the remote values configured for the campaigns, merged into a single object
- a
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 allcampaignId
and associatedvariationId
values for the visitor - a
mergedModifications
object containing all the remote values configured for the campaigns, merged into a single object
- the
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 name | type | Description |
---|---|---|
visitorId | string | Unique identifier for the application user or website visitor. This can be an ID from your database or a session ID. Learn more |
variationGroupId | string | Corresponds to a scenario in the Flagship dashboard) |
variation | object | The assigned variation information |
variation.id | string | The assigned variation ID |
variation.modifications | object | The variation modifications information |
variation.modifications.type | string | The modification type for the campaign (can be NULL, JSON, TEXT, IMAGE, HTML, FLAG, REDIRECT) |
variation.modifications.value | object | The 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 name | type | Description |
---|---|---|
campaignId | string | Identifies the campaign |
variationId | string | The 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 type | Content-Type | Status Code | HTTP response body |
---|---|---|---|
JSON | application/JSON | 200 | The JSON object defined for the campaign |
TEXT | text/plain | 200 | The text defined for the campaign |
HTML | text/HTML | 200 | The HTML defined the campaign |
IMAGE | image | 200 | The content of the image URL defined for the campaign |
REDIRECT | application/JSON | 302 | The key/value JSON object of the flags defined for the campaign |
FLAG | application/JSON | 200 | The 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
Updated over 1 year ago