Campaigns Management API

Campaign management objects enable developers to program an entire campaign via APIs. They are very useful for partners or SessionM integration engineers tasked with setting up a campaign, especially when they need to extract, transform and load data (ETL). The APIs provide a variety of management capabilities powered by endpoints that create, update, delete the model required to make a full campaign.

The following terms are critical to understanding campaigns and the objects they comprise:

• Campaign - Object in the database called AdCampaign. It stores attributes such as the campaign's name, its start and end dates, and its owner. Campaigns have three “direct reports": ad bundle (always one), line items, and achievements.
• Achievement - Also known as a "behavior," an achievement is a set of rules that define actions a customer must perform to earn an outcome. A campaign can have multiple achievements.
• Ad Bundle - This object - AdBundle in the database - stores campaign level targeting data. It is used every time SessionM needs to check if a customer qualifies for a campaign. Typically, customers might trigger an achievement and earn its outcome or simply be included as part of an audience receiving a message.
• Line Item - In the database, this object is known as an AdLineItem object. Generally, only one is created, and it holds all of the campaign's creative groups.
• Group - Also called a "creative group," it is an AdGroup object in the platform database. It controls message level targeting. When an audience is built for a message, targeting data from the ad group is combined with the targeting data from the campaign’s ad bundle. An ad group also holds the creative, which is restricted to only one creative per group.
• Creative - Also called a "message" or an "ad unit," a creative is an AdUnit object in the database. These objects store a message type, delivery settings, and, based on the message type, any message-specific data. For example, a graphic display ad unit or an activity feed message (aka tile) would have everything needed to render a graphic ad. An email message ad unit would have the messaging provider and message template information.
• Delivery Settings - Settings that define how the message is delivered. It can be one of two things: either a triggered delivery, in which case the ad unit must have the achievement_id of the behavior that triggers it; or, a scheduled delivery, in which case it must have the delivery date and time. Note too that it is the responsibility of a scheduled message to set up the jobs that will generate the audience for the message, using campaign and message targeting.

The entities described above constitute a campaign hierarchy. Together, they represent the core types of data the platform offers for the creation and maintenance of campaigns, including the ETL activities required at the beginning of an implementation. This diagram depicts how Campaign Management objects interrelate and what kinds of data they contain:

At the top of the diagram is the primary campaign object, AdCampaign. It stores basic information about the campaign, such as its name, owner, and the dates it begins and ends. This campaign object has three children - the ad bundle, the line item, and any achievements defined for the campaign.

To the far left of the diagram is the AdBundle object, which handles targeting information on the campaign level. This targeting data is shown in the related database table with AdTarget attributes for state, gender, and a tag.

Directly below AdCampaign is the AdLineItem object, which is a legacy object that serves only one function - to be a container for the creative group. That group object, called AdGroup in the database, holds message level targeting information. Like the AdBundle, it too owns a related database table with AdTarget attributes; in this case, attributes for zip, platform, and a tag. The final child of AdLineItem is AdUnit, is the actual creative, or message, being delivered for the campaign. It contains delivery option information such as a scheduled delivery date or a specific achievement trigger. In addition, the AdUnit can contain a message template, messaging provider information, and an image URL for any graphic advertisements.

And, finally, to the far right of the diagram, you can see the Achievements object, which contains any of the behaviors that must be met in order to trigger the outcomes offered by the campaign.

The Campaigns Management API provides a collection of APIs that correspond to the following areas of focus:

• Retrieving Campaigns for Management
• Managing Campaign Behaviors
• Managing Containers for Creative Groups
• Managing Creative Groups
• Managing Creatives
• Updating Campaigns
• Performing Campaign Domain Actions
• Deleting Campaigns

Retrieving Campaigns for Management

This family of APIs allows you to:

• Get all campaigns
• Get a campaign
• Get a complete hierarchy for a campaign

Get All Campaigns

Fetches all campaigns within a specific platform implementation.

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/campaigns
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains an array of campaign objects, which is shown and detailed in the response sample and in the Response Attributes for Campaign table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Get a Campaign

Fetches a campaign by either campaign ID or permalink.

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/campaigns/:campaign_id
GET /priv/v1/apps/:api_key/management/external/campaigns/:permalink            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a campaign object, which is shown and detailed in the response sample and in the Response Attributes for Campaign table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Get a Complete Hierarchy for a Campaign

Fetches a campaign's complete navigation hierarchy, detailing all of the containers, creative groups, and creatives in the campaign.

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/campaigns/:campaign_id/navigation
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a campaign object, as shown below:

{
    "status": "ok",
    "campaign": {
        "id": 730,
        "name": "Campaign Example 730",
        "status": "live",
        "starts_at": "2021-12-31T05:00:00Z",
        "ends_at": "2022-01-04T05:00:00Z",
        "line_items": [
            {
                "id": 726,
                "name": "line item for campaign 730",
                "status": "draft",
                "starts_at": "2021-12-31T05:00:00Z",
                "ends_at": "2022-01-04T05:00:00Z",
                "creative_groups": [
                    {
                        "id": 2331,
                        "name": "new creative group",
                        "status": "draft",
                        "starts_at": "2020-08-12T17:45:48Z",
                        "ends_at": "2020-09-12T17:45:48Z",
                        "creatives": [
                            {
                                "id": 2557,
                                "name": "Email File Export Test 1",
                                "status": "draft"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

This object contains the core components of a campaign hierarchy, including the campaign itself along with its container, creative group, and creative. For more information on each object, see the following sections:

• For the campaign object, see the response sample and the Response Attributes for Campaign table.
• For the line_items array object, see the response sample and the Response Attributes for Line Items table.
• For the creative_groups array object, see the response sample and the Response Attributes for Creative Groups table.
• For the creatives array object, see the response sample and the two corresponding tables, "Response Attributes for Creatives" and "Response Attributes for Messaging Platform (Issue Audience CSV)".

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Managing Campaign Behaviors

This family of APIs allows you to:

• Get all behaviors for a campaign
• Create behaviors in batch for a campaign

Get All Behaviors for a Campaign

Fetches an array of all behaviors defined for a campaign. For a comprehensive view of a campaign, see Get Information on a Campaign.

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/campaigns/:campaign_id/behaviors
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object 1

This response is for a behavior triggered by a custom event and drops a tag as its outcome. It represents a single behavior named “custom event behavior” that actually consists of 2 achievements, the goal (id 2475) and the composite(id 2476). The composite achievement duplicates the goal achievement data in its goals array.

In addition to a status key-value pair, the response object returned by the method contains a behaviors array object, as shown below:

{
    "behaviors": [
        {
            "data": {
                "consecutive": false,
                "eligible_spend": null,
                "max_times_achievable": null,
                "max_times_achievable_per_month": null,
                "max_times_achievable_per_period": null,
                "max_times_achievable_per_year": null,
                "min_time_between_events": null,
                "min_time_between_events_count": 1,
                "period": 7776000
            },
            "errors": {},
            "id": 2475,
            "name": "MMC-72b1c697-7090-4aef-9f6e-4f0a7e24cd15",
            "points": 0,
            "tags": null
        },
        {
            "data": {
                "consecutive": false,
                "eligible_spend": null,
                "goals_csv_data": "2475,1,true,0,1,false\n",
                "max_times_achievable": null,
                "max_times_achievable_per_period": null,
                "min_time_between_events": null,
                "period": 86400,
                "use_same_period": false
            },
            "errors": {},
            "goal_groups": [
                {
                    "goal_count": 1,
                    "goals": [
                        {
                            "achievement": {
                                "data": {
                                    "consecutive": false,
                                    "eligible_spend": null,
                                    "max_times_achievable": null,
                                    "max_times_achievable_per_month": null,
                                    "max_times_achievable_per_period": null,
                                    "max_times_achievable_per_year": null,
                                    "min_time_between_events": null,
                                    "min_time_between_events_count": 1,
                                    "period": 7776000
                                },
                                "errors": {},
                                "event_count": 1,
                                "id": 2475,
                                "name": "MMC-72b1c697-7090-4aef-9f6e-4f0a7e24cd15",
                                "points": 0,
                                "tags": null
                            }
                        }
                    ]
                }
            ],
            "id": 2476,
            "name": "custom event behavior",
            "outcomes": [],
            "points": 0,
            "tags": "custom_behavior_completed"
        }
    ],
    "status": "ok"
}

This behaviors array object is detailed in the tables describing the behaviors array that is returned when creating behaviors in batch for a campaign. You can consult all of the tables in that section, starting with the Response Attributes for Behaviors table.

Response Object 2

This response is for a purchase behavior that requires the user to purchase any 3 items and award 10 points as its outcome.

In addition to a status key-value pair, the response object returned by the method contains a behaviors array object, as shown below:

{
    "behaviors": [
        {
            "data": {
                "consecutive": false,
                "eligible_spend": null,
                "max_times_achievable": null,
                "max_times_achievable_per_month": null,
                "max_times_achievable_per_period": null,
                "max_times_achievable_per_year": null,
                "min_time_between_events": null,
                "min_time_between_events_count": 1,
                "period": 7776000
            },
            "errors": {},
            "id": 2477,
            "name": "MMC-07431719-e3bd-46e9-8f72-f7a6bead9ceb",
            "points": 0,
            "tags": null
        },
        {
            "data": {
                "consecutive": false,
                "eligible_spend": null,
                "goals_csv_data": "2477,1,true,0,1,false\n",
                "max_times_achievable": null,
                "max_times_achievable_per_period": null,
                "min_time_between_events": null,
                "period": 86400,
                "use_same_period": false
            },
            "errors": {},
            "goal_groups": [
                {
                    "goal_count": 1,
                    "goals": [
                        {
                            "achievement": {
                                "data": {
                                    "consecutive": false,
                                    "eligible_spend": null,
                                    "max_times_achievable": null,
                                    "max_times_achievable_per_month": null,
                                    "max_times_achievable_per_period": null,
                                    "max_times_achievable_per_year": null,
                                    "min_time_between_events": null,
                                    "min_time_between_events_count": 1,
                                    "period": 7776000
                                },
                                "errors": {},
                                "event_count": 1,
                                "id": 2477,
                                "name": "MMC-07431719-e3bd-46e9-8f72-f7a6bead9ceb",
                                "points": 0,
                                "tags": null
                            }
                        }
                    ]
                }
            ],
            "id": 2478,
            "name": "purchase event test",
            "outcomes": [
                {
                    "account_id": null,
                    "created_at": "2017-10-18T21:00:48Z",
                    "id": 97,
                    "model_id": 87,
                    "model_type": "Offer",
                    "organization_id": 13,
                    "updated_at": "2017-10-18T21:00:48Z"
                }
            ],
            "points": 10,
            "tags": ""
        }
    ],
    "status": "ok"
}

This behaviors array object is detailed in the tables describing the behaviors array that is returned when creating behaviors in batch for a campaign. You can consult all of the tables in that section, starting with the Response Attributes for Behaviors table.

Response Object 3

This response is for a purchase behavior that requires the user to purchase any item. The response also demonstrates the start/end time behavior restriction. For more information, see the event_filters object in the response below.

In addition to a status key-value pair, the response object returned by the method contains a behaviors array object, as shown below:

{
    "status": "ok",
    "behaviors": [
        {
            "id": 2506,
            "name": "MMC-2aef35f7-bff9-4df4-9e26-196816179f4b",
            "points": 0,
            "tags": null,
            "data": {
                "result_trigger": null,
                "eligible_spend": null,
                "precise_event_count": null,
                "unit_precision": null,
                "min_time_between_events": null,
                "min_time_between_events_count": 1,
                "period": 7776000,
                "max_times_achievable": null,
                "max_times_achievable_per_period": null,
                "max_times_achievable_per_month": null,
                "max_times_achievable_per_year": null,
                "consecutive": false
            },
            "errors": {}
        },
        {
            "id": 2507,
            "name": "goal start/end test",
            "points": 0,
            "tags": "",
            "data": {
                "result_trigger": null,
                "eligible_spend": null,
                "precise_event_count": null,
                "unit_precision": null,
                "goals_csv_data": "2506,1,true,0,1,false\n",
                "period": 86400,
                "max_times_achievable": null,
                "max_times_achievable_per_period": null,
                "min_time_between_events": null,
                "consecutive": false,
                "use_same_period": false
            },
            "errors": {},
            "goal_groups": [
                {
                    "goal_count": 1,
                    "goals": [
                        {
                            "achievement": {
                                "id": 2506,
                                "name": "MMC-2aef35f7-bff9-4df4-9e26-196816179f4b",
                                "points": 0,
                                "tags": null,
                                "data": {
                                    "result_trigger": null,
                                    "eligible_spend": null,
                                    "precise_event_count": null,
                                    "unit_precision": null,
                                    "min_time_between_events": null,
                                    "min_time_between_events_count": 1,
                                    "period": 7776000,
                                    "max_times_achievable": null,
                                    "max_times_achievable_per_period": null,
                                    "max_times_achievable_per_month": null,
                                    "max_times_achievable_per_year": null,
                                    "consecutive": false
                                },
                                "errors": {},
                                "event_count": 1,
                            }
                        }
                    ]
                }
            ],
            "outcomes": []
        }
    ]
}

This behaviors array object is detailed in the tables describing the behaviors array that is returned when creating behaviors in batch for a campaign. You can consult all of the tables in that section, starting with the Response Attributes for Behaviors table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create Behaviors in Batch for a Campaign

Creates behaviors in batch for a campaign. The request object creates a campaign behavior triggered by a custom event (my_custom_event). The request then awards an offer and tags the user (custom_behavior_completed) as its outcomes.

Endpoints

This method offers the following endpoints:

POST /priv/v1/apps/:api_key/management/campaigns/:campaign_id/behaviors/_batch
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a behaviors array, as shown below:

{
   "behaviors":[
      {
          "name": "custom event behavior - campaign 730",
          "tags": "custom_behavior_completed",
          "data": {
              "period": 86400,
              "max_times_achievable": null,
              "use_same_period": false
          },
          "goal_groups": [
              {
                  "goals": [
                      {
                          "achievement": {
                              "name": "goal achievement for custom event behavior - campaign 730",
                              "internal_event_name": "my_custom_event",
                              "event_count": 1,
                              "data": {
                                  "period": 7776000,
                                  "max_times_achievable": null,
                                  "max_times_achievable_per_period": null,
                                  "min_time_between_events": null,
                                  "min_time_between_events_count": 1,
                                  "consecutive": false
                              }
                          }
                      }
                  ]
              }
          ],
          "outcome_config":[
            {
               "deal":{
                  "id": "514dafae-14ab-4104-b4da-3b2ad08f10d5"
               }
            }
         ]
      }
   ]
}

This object is detailed in the following table:

Request Attributes for Behaviors

Request Attributes for Data

Request Attributes for Achievement

Response Object

In addition to a status key-value pair, the response object returned by the method contains a behaviors array, as shown below:

{
   "status":"ok",
   "behaviors":[
      {
         "id":2480,
         "name":"New behavior",
         "points":0,
         "tags":"my_tag_to_target_away_from_user",
         "data":{
            "eligible_spend":null,
            "goals_csv_data":"2479,1,false,0,0,false\n",
            "period":86400,
            "max_times_achievable":1,
            "max_times_achievable_per_period":null,
            "min_time_between_events":null,
            "consecutive":false,
            "use_same_period":false
         },
         "errors":{

         },
         "goal_groups":[
            {
               "goal_count":0,
               "goals":[
                  {
                     "achievement":{
                        "id":2479,
                        "name":"MMC-offer_issued",
                        "points":0,
                        "tags":null,
                        "data":{
                           "eligible_spend":null,
                           "min_time_between_events":null,
                           "min_time_between_events_count":1,
                           "period":86400,
                           "max_times_achievable":1,
                           "max_times_achievable_per_period":null,
                           "max_times_achievable_per_month":null,
                           "max_times_achievable_per_year":null,
                           "consecutive":false
                        },
                        "errors":{
                        },
                        "event_count":1,
                     }
                  }
               ]
            }
         ],
         "outcomes":[
            {
               "account_id":null,
               "created_at":"2020-08-13T15:51:52Z",
               "id":357,
               "model_id":120,
               "model_type":"Offer",
               "organization_id":13,
               "updated_at":"2020-08-13T15:51:52Z"
            }
         ]
      }
   ]
}

This object is detailed in the following table:

Response Attributes for Behavior

Response Attributes for Data (Achievement)

Response Attributes for Goal Group

Response Attributes for Achievement

Response Attributes for Outcomes

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Managing Containers for Creative Groups

This family of APIs allows you to:

• Create a container for a campaign
• Get all containers for a campaign
• Get a container by container ID
• Update a container
• Delete a container

Create a Container for a Campaign

Creates a container in a campaign for creative groups.

Endpoints

This method offers the following endpoints:

POST /priv/v1/apps/:api_key/management/campaigns/:campaign_id/line_items
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a line_item object which is shown below:

{
  "line_item": {
      "name": "new line item",
      "starts_at": "2020-08-13 15:52:33 -0400",
      "ends_at": "2020-08-22 15:52:33 -0400",
      "status": "live"
  }
}

This object is detailed in the following table:

Request Attributes for Line Item

Response Object

In addition to a status key-value pair, the response object returned by the method contains a line_items array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Line Items table.

Get All Containers for a Campaign

Fetches an array of containers (line item objects) for creative groups associated with a campaign by campaign ID. Note that there is only a single line item per campaign.

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/campaigns/:campaign_id/line_items
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a line_items array, as shown below:

{
  "line_items": [
    {
        "campaign_id": 726,
        "starts_at": "2020-08-12T17:45:48Z",
        "ends_at": "2020-09-12T17:45:48Z",
        "id": 722,
        "name": "behaviors api test 2",
        "status": "live"
     }
   ],
   "status": "ok"
}

This array is detailed in the following table:

Response Attributes for Line Items

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Get a Container by Container ID

Fetches a container (line item) for creative groups associated with a campaign by container ID.

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/line_items/:line_item_id
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a line_items array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Line Items table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Container

Updates a container (line item) of creative groups.

Endpoints

This method offers the following endpoints:

PUT /priv/v1/apps/:api_key/management/line_items/:line_item_id
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a line_item object which is shown below:

{
  "line_item": {
      "name": "updated new line item",
      "starts_at": "2020-08-13 15:52:33 -0400",
      "ends_at": "2020-08-22 15:52:33 -0400",
      "status": "live"
  }
}

This object is detailed in the following table:

Request Attributes for Line Item

Response Object

In addition to a status key-value pair, the response object returned by the method contains a line_items array, as shown below:

{
  "line_items": [
    {
        "campaign_id": 726,
        "starts_at": "2020-08-13 15:52:33 -0400",
        "ends_at": "2020-08-22 15:52:33 -0400",
        "id": 722,
        "name": "updated new line item",
        "status": "live"
     }
   ],
   "status": "ok"
}

This array is detailed in the following table:

Response Attributes for Line Items

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete a Container

Deletes a container (line item) of creative groups.

Endpoints

This method offers the following endpoints:

DELETE /priv/v1/apps/:api_key/management/line_items/:line_item_id
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a line_item object, as shown below:

{
  "status": "ok",
  "line_item": {
    "id": 372,
    "name": "Line Item Example[DELETED AT Oct 25, 2017 03:50 pm]",
    "status": "live",
    "campaign_id": 367,
    "starts_at": "2014-12-31T05:00:00Z",
    "ends_at": "2015-01-04T05:00:00Z"
  }
}

This object is detailed in the Response Attributes for Line Items table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Managing Creative Groups

This family of APIs allows you to:

• Get all creative groups in a container
• Get a creative group in a container
• Create a creative group in a container
• Update a creative group in a container
• Delete a creative group from a container

Get All Creative Groups in a Container

Fetches all creative groups in a container (line item).

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/line_items/:line_item_id/creative_groups
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creative_groups array, as shown below:

{
    "creative_groups": [
        {
            "ends_at": "2020-09-12T17:45:48Z",
            "id": 2326,
            "line_item_id": 722,
            "name": "Email File Export",
            "starts_at": "2020-08-12T17:45:48Z",
            "status": "live"
        },
        {
            "ends_at": "2020-09-12T17:45:48Z",
            "id": 2324,
            "line_item_id": 722,
            "name": "BEHAVIOR AD STAT",
            "starts_at": "2020-08-12T17:45:48Z",
            "status": "live"
        }
    ],
    "status": "ok"
}

This array is detailed in the following table:

Response Attributes for Creative Groups

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Get a Creative Group in a Container

Fetches a specific creative group in a container (line item).

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creative_groups array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Creative Groups table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a Creative Group in a Container

Creates creative groups for a container (line item).

Endpoints

This method offers the following endpoints:

POST /priv/v1/apps/:api_key/management/line_items/:line_item_id/creative_groups
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a creative_group object which is shown below:

{
  "creative_group": {
    "name":"Group Name",
    "status":"live",
    "starts_at":"2014-12-31T05:00:00Z",
    "ends_at":"2015-01-04T05:00:00Z"}
}

This object is detailed in the following table:

Request Attributes for Creative Group

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creative_groups array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Creative Groups table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Creative Group in a Container

Updates a creative group for a container (line item).

Endpoints

This method offers the following endpoints:

PUT /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a creative_group object which is shown below:

{
  "creative_group": {
    "name":"Updated Group 3",
    "ends_at":"2015-02-04T05:00:00Z"}
}

This object is detailed in the Request Attributes for Creative Groups table.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creative_groups array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Creative Groups table. The response would include the new values for any updated attributes.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete a Creative Group from a Container

Deletes a creative group from a container (line item).

Endpoints

This method offers the following endpoints:

DELETE /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creative_group object, as shown below:

{
  "status": "ok",
  "creative_group": {
    "id": 12,
    "name": "Updated Group 2[DELETED AT Jan 1, 2015 05:00 am]",
    "status": "live",
    "line_item_id": 12,
    "starts_at": "2014-12-31T05:00:00Z",
    "ends_at": "2015-02-04T05:00:00Z"
  }
}

This object is detailed in the Response Attributes for Creative Groups table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Managing Creatives

This family of APIs allows you to:

• Get all creatives for a group
• Get a creative for a group
• Create a creative for a group
• Update a creative for a group
• Delete a creative from a group

Get All Creatives for a Group

Fetches all creatives for a group.

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id/creatives
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creatives array, as shown below:

{
    "creatives": [
        {
            "ad_type": "issue_audience_csv",
            "application_id": 36,
            "creative_group_id": 2326,
            "creative_type": "issue-audience-csv",
            "id": 2553,
            "issue_audience_csv": {
                "delivery_method": "scheduled",
                "issue_offer_date": "2020-08-13T01:21:48+00:00",
                "next_ad_type": "interstitial",
                "offer_ids": [],
                "orientation": "portrait",
                "portal_description": "Check out this ad!",
                "portal_icon": "/images/icon_starv1_94x94.png",
                "scheduled_delivery_date": "2020-08-15T01:21:48+00:00",
                "second_sn_audience_guid": "cddea1ae-dcb7-11ea-95db-a7d2986d963d",
                "template_id": "my_creative_template",
                "trigger_type": "standard"
            },
            "name": "Email File Export",
            "status": "draft"
        }
    ],
    "status": "ok"
}

Note that actual responses may vary based on message type. This array is detailed in the following table:

Response Attributes for Creatives

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Get a Creative for a Group

Fetches a creative for a creative group.

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/management/creatives/:creative_id
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creatives array object, a sample for which is shown and detailed in the response sample and in the two corresponding tables, "Response Attributes for Creatives" and "Response Attributes for Messaging Platform (Issue Audience CSV)".

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a Creative for a Group

Creates a creative for a group.

Endpoints

This method offers the following endpoints:

POST /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id/creatives
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a creative object which is shown below:

{
    "creative": {
        "ad_type": "issue_audience_csv",
        "application_id": 36,
        "creative_type": "issue-audience-csv",
        "issue_audience_csv": {
            "delivery_method": "scheduled",
            "scheduled_delivery_date": "2020-08-15T01:21:48+00:00",
            "template_id": "my creative template"
        },
        "name": "Email File Export Test 1",
        "status": "draft"
    }
}

This object is detailed in the following table:

Request Attributes for Creative

Request Attributes for Issue Audience CSV

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creatives array object, a sample for which is shown and detailed in the response sample and in the two corresponding tables, "Response Attributes for Creatives" and "Response Attributes for Messaging Platform (Issue Audience CSV)".

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Creative for a Group

Updates a creative for a group.

Endpoints

This method offers the following endpoints:

PUT /priv/v1/apps/:api_key/management/creatives/:creative_id
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a creative object which is shown and detailed in the request sample and in the two corresponding tables, "Request Attributes for Creative" and "Request Attributes for Issue Audience CSV".

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creatives array object, a sample for which is shown and detailed in the response sample and in the two corresponding tables, "Response Attributes for Creatives" and "Response Attributes for Messaging Platform (Issue Audience CSV)".

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete a Creative from a Group

Deletes a creative from a group.

Endpoints

This method offers the following endpoints:

DELETE /priv/v1/apps/:api_key/management/creatives/:creative_id
            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creatives array object, a sample for which is shown and detailed in the response sample and in the two corresponding tables, "Response Attributes for Creatives" and "Response Attributes for Messaging Platform (Issue Audience CSV)".

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Updating Campaigns

Updates a campaign by campaign ID or permalink.

Endpoints

This method offers the following endpoints:

PUT /priv/v1/apps/:api_key/management/campaigns/:campaign_id
PUT /priv/v1/apps/:api_key/management/external/campaigns/:permalink            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a campaign object, as shown below:

{
  "campaign": {
    "name":"Campaign Example - name change",
    "status":"live",
    "starts_at":"2021-12-31T05:00:00Z",
    "ends_at":"2022-01-04T05:00:00Z
  }
}  

This object is detailed in the following table:

Request Attributes for Campaign

Response Object

In addition to a status key-value pair, the response object returned by the method contains a campaign object, which is detailed in Response Attributes for Campaign table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Performing Campaign Domain Actions

Campaign domain actions programmatically force customers to progress through a sequence of campaign milestones without having to actually perform an action. Normally, these actions are written to the platform through live integrations, which include purchases, store visits, and custom events.

These actions are performed for a specific campaign by some combination of user IDs (internal or external) and campaign ID or permalink. The endpoints available with this API complete a campaign by earning all of the simple behaviors (goals) belonging to a composite behavior. Doing so earns the composite behavior of a given campaign.

Note: Once the campaign has already been completed - the behaviors have reached their frequency cap - it can’t be completed again.

Implementation Notes for Performing Campaign Domain Actions Using V2 APIs

As you work with any of the V2 endpoints that perform domain actions via V2 routes, consider some important implementation details.

Base controller for any of the Campaigns V2 APIs: /dev/core1/app/controllers/priv/v2/users/campaigns/base_controller.rb

Controller for the perform routes: /dev/core1/app/controllers/priv/v2/users/campaigns_controller.rb (edited)

Endpoints that perform domain actions offer a few different kinds of parameters:

Sections:

• progress_section?
• behaviors_section?
• offers_section?
• redemptions_section?

Filters:

• eligible_filter?
• ineligible_filter?

Creatives:

• promotion_creative?
• tile_creative?

These parameters are defined in the "Endpoint Parameters" section below.

Sample Curl:

curl -g -H 'Content-Type:application/json' -u ':redacted' 'https://api-acme.stg-sessionm.com/priv/v2/apps/64f15f67f03de170fb01dd41c0a4321e5d5dfc01/users/c4ce8a2e-bd20-11e8-83a5-ef4eff57e974/campaigns/565?sections[]=behaviors&sections[]=progress,&sections[]=offers&sections[]=redemptions'

Endpoints

This method offers the following endpoints:

POST /priv/v2/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/perform
POST /priv/v2/apps/:api_key/users/:user_id/external/campaigns/:permalink/perform
POST /priv/v2/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/perform
POST /priv/v2/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/perform

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object, as shown below:

{
  "domain": "complete_campaign"
}

This object is detailed in the following table:

Request Attributes for Domain

Response Object

In addition to a status key-value pair, the response object returned by the method contains a campaign object, as shown below:

{
  "status": "ok",
  "campaign": {
      "campaign_id": 401,
      "campaign_permalink": "7ecea43c-d478-11e7-97fa-26a9d64d3094",
      "ends_at": "2018-12-31 10:33:20",
      "name": "New Campaign",
      "qualified": false,
      "starts_at": "2017-11-28 05:34:20",
      "status": "completed"
  }
}

This object is detailed in Response Attributes for Campaign table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Deleting Campaigns

Deletes a campaign by campaign ID or permalink.

Endpoints

This method offers the following endpoints:

DELETE /priv/v1/apps/:api_key/management/campaigns/:campaign_id
DELETE /priv/v1/apps/:api_key/management/external/campaigns/:permalink            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a campaign object, which is detailed in Response Attributes for Campaign table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.