Campaigns API

Campaign objects represent scheduled and targeted customer engagements of any kind: messaging, promotions, games and display advertising.

You can create campaigns and configure their associated customer actions and outcomes. At the same time, campaigns allow you to collect data and analyze campaign effectiveness. With that data, you can trigger additional marketing activities as well as target future campaigns. Campaigns can target specific audience segments, as well as support a set of rules around campaign duration, opt-in requirements, delivery methods, creative assets and desired customer actions.

The platform supports a number of campaign types, including:

• Inbox - Push in-app mail messages for customers to read, engage with and delete.
• Activity Feed - Create dynamic and targeted message tiles in a scrollable activity feed that displays for a customer. These feeds are configurable and resemble the activity feeds typical in social media platforms such as Facebook.
• Push - Scheduled and triggered push messaging campaigns.
• Rich Media - Create informative rich media messages to drive a call to action.
• Video - Engage customers with video messages and a call to action.
• Action-based Campaigns - Any of the above campaigns can be triggered when a specific action is completed.

Campaign objects provide SessionM partners with the ability to query campaigns targeted to a specific customer and fetch customer-specific state information related to campaigns. In addition, some of the methods retrieve a campaign along with its data and then validate a customer's eligibility for the specified 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.

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

• Opting Customers into Campaigns
• Retrieving Campaigns for Customers
• Retrieving Campaigns

Opting Customers into Campaigns

Opts a customer into a campaign for which they are eligible. This transaction updates their status and make them able to earn the incentive associated with this campaign.

Note that to enable "opt-ins," a campaign must be created with optin_required set to "true": optin_required=true.

Endpoints for Opting Customers into Campaigns

This method offers the following endpoints:

REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/campaigns/:campaign_id/opt_in
GET /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:campaign_id/opt_in

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 for Opting Customers into Campaigns

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

Request Object for Opting Customers into Campaigns

Not applicable.

Response Object for Opting Customers into Campaigns

Since this method's response object is identical to what is returned for the method that returns all campaigns, see the "Response Object" section in Retrieve All Campaigns for a Customer for more information.

Statuses and Errors for Opting Customers into Campaigns

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:

s

Note that all of the above errors apply only when a customer has opted in to a campaign.

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

Retrieving Campaigns for Customers

This family of APIs allows you to:

• Get all campaigns for a specified customer
• Get customer progress for a campaign
• Get all active campaigns eligible for a customer
• Get a specific campaign for a customer by internal user ID and campaign ID
• Get a specific campaign for a customer by ID and either campaign permalink or ID

Get All Campaigns for a Specified Customer

Fetches all of the campaigns associated with a specified or authorization token. Note that the endpoints that utilize a user_id or external_id are available for registered customers (users); however, GET /api/v1/apps/:api_key/campaigns?auth_token=xxxxx applies to unregistered, anonymous customers.

Endpoints for Get All Campaigns for a Specified Customer

This method offers the following endpoints:

REST Endpoints (Retrieve All Campaigns for a Specified Customer)

GET /priv/v1/apps/:api_key/users/:user_id/campaigns
GET /priv/v1/apps/:api_key/external/users/:external_id/campaigns
GET /api/v1/apps/:api_key/campaigns?auth_token=xxxxx

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 for Get All Campaigns for a Specified Customer

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

Request Object for Get All Campaigns for a Specified Customer

Not applicable.

Response Object for Get All Campaigns for a Specified Customer

In addition to a status key-value pair, the response object returned by the method contains a campaigns object, which contains tiles and promotions arrays shown below:

JSON Response (Retrieve All Campaigns for a Single Customer)

{
    "status": "ok",
    "campaigns": {
        "tiles": [
            {
                "campaign_id": 1255,
                "name": "promotionCampaign",
                "group_id": 2917,
                "creative_id": 2983,
                "start_date": "2017-07-03 19:04:18",
                "end_date": "2017-08-03 19:04:18",
                "opt_in_starts_at": "2017-07-03 19:04:18",
                "opt_in_ends_at": "2017-08-03 19:04:18",
                "permalink": "6a04f24c-6022-11e7-8c24-3bcbbae62f9c",
                "template": {
                    "type": "internal_tile",
                    "message": {
                        "points": 0
                    },
                    "action": {
                        "tracking_urls": [
                            "https://api-qa4.q-sessionm.com/api/v1/apps/70261ce1e55ee3a5c282d48bdd4fa343230c04e0/creatives/2983/stats/3726c65e-7de4-11e7-959f-f9d291045c00/seen/track?auth_token=v2--Ga0yJV7TyMJsIjOZ40MitXJQanHlX_SrG3IZl-TmYXY=--QyLCZ-H6d08Ny9dzS_xavtjKjOMT2HznmZz8nfGcOm3NXKduOSzkkJpZ4bgoPKjQsA==&xsid=48792ee2-0e5e-11e7-8716-9311a9d25bb0&locale=en-us"
                        ],
                        "event_meta_data": {
                            "ad_unit_id": 2983,
                            "ad_stat_id": "3726c65e-7de4-11e7-959f-f9d291045c00"
                        }
                    }
                },
                "progress": {
                    "state": "completed"
                },
                "behaviors": {},
                "version": 2,
                ""
            }
        ],
        "promotions": [
            {
                "campaign_id": 1064,
                "name": "Launch 2",
                "group_id": 2578,
                "creative_id": 2640,
                "start_date": "2017-06-15 18:35:37",
                "end_date": "2017-07-15 18:35:37",
                "opt_in_starts_at": "2017-06-15 18:35:37",
                "opt_in_ends_at": "2017-07-15 18:35:37",
                "permalink": "6ce11f7c-51f9-11e7-822a-02d3bae62f9c",
                "template": {
                    "type": "internal_full_page",
                    "html_payload": "https://api-qa4.q-sessionm.com/apps/70261ce1e55ee3a5c282d48bdd4fa343230c04e0/users/48792ee2-0e5e-11e7-8716-93115045e6c0/ads/2640"
                },
                "progress": {
                    "state": "completed"
                },
                "behaviors": {},
                "version": 2
            },
            {
                "campaign_id": 1443,
                "name": "TEstt0714441",
                "group_id": 3232,
                "creative_id": 3364,
                "start_date": "2017-07-14 20:37:16",
                "end_date": "2017-08-14 20:37:16",
                "opt_in_starts_at": "2017-07-14 20:37:16",
                "opt_in_ends_at": "2017-08-14 20:37:16",
                "permalink": "3964b522-68d4-11e7-8479-4fdfbae62f9c",
                "template": {
                    "type": "internal_full_page",
                    "html_payload": "https://api-qa4.q-sessionm.com/apps/70261ce1e55ee3a5c282d48bdd4fa343230c04e0/users/48792ee2-0e5e-11e7-8716-93115045e6c0/ads/3364"
                },
                "progress": {
                    "state": "in_progress",
                    "behaviors": [
                        {
                            "behavior_id": 1444,
                            "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",
                            "event_name": "3dac9302-68d4-11e7-9412-9e32bae62f9c",
                            "name": "TEstt0714441 Campaign Action 1",
                            "progress": 0,
                            "goal": 1
                        }
                    ]
                },
                "behaviors": {
                    "t_estt0714441 campaign action 1": {
                        "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",
                        "type": "composite",
                        "points": 0,
                        "achieved": 4,
                        "max_times_repeatable": null,
                        "max_times_repeatable_per_period": null,
                        "period": 7776000,
                        "min_time_between_events": null,
                        "consecutive": false,
                        "goals": {
                            "campaigns.1443.loaded": {
                                "type": "goal",
                                "points": 4,
                                "completed": false,
                                "required": true,
                                "earn_count": 1,
                                "group_id": "0",
                                "progress": {
                                    "event_name": "campaigns.1443.loaded",
                                    "type": "count",
                                    "points": 4,
                                    "max_times_repeatable": null,
                                    "max_times_repeatable_per_period": null,
                                    "period": 7776000,
                                    "min_time_between_events": null,
                                    "consecutive": false,
                                    "achieved": 4,
                                    "current_count": 0,
                                    "total_count": 1
                                }
                            }
                        },
                        "groups": {
                            "0": {
                                "type": "group",
                                "current_count": 0,
                                "total_count": 1,
                                "num_goals": 1,
                                "completed": false
                            }
                        }
                    }
                },
                "version": 2
            }
        ]
    }
}

The attributes for each are identical and are covered in a combined section below.

Tiles and Promotions Array

The following table provides details on the tiles and promotions arrays, which can contain multiple campaigns:

Response Attributes for Campaigns in Tiles and Promotions Arrays

Template Object

The following table provides details on the template object:

Response Attributes for Template

Action Object

The following table provides details on the action object:

Response Attributes for Action

Behaviors Array

The following table provides details on the behaviors array:

Response Attributes for Behaviors Array

Behaviors Object

The following table provides details on the behaviors object:

Response Attributes for Behaviors Object

Goals Object

The following table provides details on the goals object:

Response Attributes for Goals Object

Progress Object

The following table provides details on the progress object:

Response Attributes for Progress Object

Groups Object

The following table provides details on the groups object:

Response Attributes for Groups Object

Statuses and Errors for Get All Campaigns for a Specified Customer

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 Customer Progress for a Campaign

Fetches a customer's progress for a specified campaign, even after the campaign ends. Responses display the customer's state in the campaign and the progress they've made engaging in a behavior.

Note that individual campaigns can be specified using either the ad_campaign_id or permalink parameters.

Endpoints for Get Customer Progress for a Campaign

This method offers the following endpoints:

REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/progress
GET /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/progress
GET /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/progress
GET /priv/v1/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/progress
GET /api/v1/apps/:api_key/campaigns/:ad_campaign_id/progress?auth_token=
GET /api/v1/apps/:api_key/external/campaigns/:permalink/progress?auth_token=

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 for Get Customer Progress for a Campaign

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

Request Object for Get Customer Progress for a Campaign

Not applicable.

Response Object for Get Customer Progress for a Campaign

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

JSON Response

{
    "status": "ok",
    "campaign": {
        "state": "qualified",
        "behaviors": [
        {
              "behavior_id": 525,
              "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",
              "event_name": "ada7af74-9710-11e7-8803-9bbc32d1fae9",
              "name": "my_campaign_event_name",
              "progress": 0,
              "goal": 1
        }
        ]
    }
}

JSON Response (With Customer Opting In)

{
    "status": "ok",
    "campaign": {
        "opted_in": true,
        "state": "opted_in",
        "behaviors": [
            {
                "behavior_id": 543,
                "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",
                "event_name": "bce50a3c-9c8c-11e7-832f-e29b32d1fae9",
                "name": "moose_sleep_b",
                "progress": 0,
                "goal": 1
            }
        ]
    }
}

JSON Response (With Customer Opting Out)

{
    "status": "ok",
    "campaign": {
        "opted_in": false,
        "state": "opted_out",
        "behaviors": [
            {
                "behavior_id": 525,
                "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",
                "event_name": "ada7af74-9710-11e7-8803-9bbc32d1fae9",
                "name": "pretty_llamas-b",
                "progress": 0,
                "goal": 1
            }
        ]
    }
}

This object is detailed in the following table:

Response Attributes for Campaign

Statuses and Errors for Get Customer Progress for a Campaign

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 All Active Campaigns Eligible for a Customer

Fetches all active campaigns that a customer is eligible for by either internal or external user ID.

Note that these are V2 endpoints. You can consult Implementation Notes for Retrieving Campaigns Using V2 APIs for additional implementation details.

Endpoints for Get All Active Campaigns Eligible for a Customer

This method offers the following endpoints:

REST Endpoints

GET /priv/v2/apps/:api_key/users/:user_id/campaigns
GET /priv/v2/apps/:api_key/external/users/:external_id/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 for Get All Active Campaigns Eligible for a Customer

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

Request Object for Get All Active Campaigns Eligible for a Customer

Not applicable.

Response Object for Get All Active Campaigns Eligible for a Customer

The response object returned by the method contains a status key-value pair, a few relevant attributes and a campaigns array, as shown in two sample below:

JSON Response

{
  "page": 1,
  "page_size": 20,
  "number_of_pages": 1,
  "status": "ok",
  "campaigns": [
    {
      "campaign_id": 1,
      "campaign_permalink": "45650900-d457-11e7-9d65-94bc328254fd",
      "creative": {
        "tile": {
          "message": {
            "header": "Test Header",
            "subheader": "Test Subheader",
            "description": "Test Description",
            "icon_url": "http://bit.ly/foo.png",
            "image_url": "http://getm.pt/foo.png",
            "points": 20
          },
          "action": {
            "type": "open_ad",
            "url": "http://ads.host/api/v1/apps/xyz15cbf87b9068363df55fc6344e05b550e49c98060/creatives/2/stats/457869f0-d457-11e7-99dd-ee69328254fd/click/redir?auth_token=&xsid=457583c0-d457-11e7-88dd-f3698c9fdcfd&locale=en-us",
            "tracking_urls": [
              "http://ads.host/priv/v1/apps/xyz15cbf87b9068363df55fc6344e05b550e49c98060/users/457583c0-d457-11e7-88dd-f369328254fd/creatives/2/stats/457869f0-d457-11e7-99dd-ee69328254fd/seen/track?xsid=457583c0-d457-11e7-88dd-f3698c9fdcfd&locale=en-us"
            ],
            "event_meta_data": {
              "ad_unit_id": 2,
              "ad_stat_id": "457869f0-d457-11e7-99dd-ee69328254fd"
            }
          }
        }
      },
      "ends_at": "2017-12-01 16:14:55",
      "name": "Campaign 1",
      "opt_in_ends_at": "2017-12-01 16:14:55",
      "opt_in_starts_at": "2017-11-27 16:14:55",
      "qualified": false,
      "starts_at": "2017-11-27 16:14:55",
      "status": "not_qualified"
    }
  ]
}

This object is detailed in the following table:

Response Attributes for Campaigns Array

Response Attributes for Tile

Response Attributes for Message

Response Attributes for Action

Statuses and Errors for Get All Active Campaigns Eligible for a Customer

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.

Get a Specific Campaign for a Customer by Internal User ID and Campaign ID

Fetches a campaign that a user is eligible for by an internal user ID and a campaign ID.

Note that this is a V2 endpoint. You can consult Implementation Notes for Retrieving Campaigns Using V2 APIs for additional implementation details.

Endpoints for Get a Specific Campaign for a Customer by Internal User ID and Campaign ID

This method offers the following endpoints:

REST Endpoints

GET /priv/v2/apps/:api_key/users/:user_id/campaigns/:ad_campaign_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 for Get a Specific Campaign for a Customer by Internal User ID and Campaign ID

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

Request Object for Get a Specific Campaign for a Customer by Internal User ID and Campaign ID

Not applicable.

Response Object for Get a Specific Campaign for a Customer by Internal User ID and Campaign ID

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

JSON Response

{
  "status": "ok",
  "campaign": {
    "campaign_id": 11,
    "campaign_permalink": "9f86dafb-b999-4b61-8c71-59d9d45628f2",
    "creative": {
      "promotion": {
        "type": "internal_full_page",
        "html_payload": "http://ads.host/apps/xyz130d6fdeb9ef1af877dae1d3b749e842727543cc5/users/5a296e48-d458-11e7-9958-5691328254fd/ads/11"
      }
    },
    "ends_at": "2017-12-01 16:22:41",
    "name": "Campaign 11",
    "opt_in_ends_at": "2017-12-01 16:22:41",
    "opt_in_starts_at": "2017-11-27 16:22:41",
    "opted_in": true,
    "qualified": true,
    "starts_at": "2017-11-27 16:22:41",
    "status": "completed"
  }
}

Most of the attributes of this Campaign object are described in the Response Attributes for Campaign table. However, the creative object - which resides within the campaign object - does contain a promotion object that is detailed in the following table:

Response Attributes for Promotion

Statuses and Errors for Get a Specific Campaign for a Customer by Internal User ID and Campaign ID

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.

Get a Specific Campaign for a Customer by ID and Either Campaign Permalink or ID

Fetches a campaign that a user is eligible for by ID (internal or external) and campaign (permalink or ID).

Note that these are V2 endpoints. You can consult Implementation Notes for Retrieving Campaigns Using V2 APIs for additional implementation details.

Endpoints for Get a Specific Campaign for a Customer by ID and Either Campaign Permalink or ID

This method offers the following endpoints:

REST Endpoints

GET /priv/v2/apps/:api_key/users/:user_id/external/campaigns/:permalink
GET /priv/v2/apps/:api_key/external/users/:external_id/campaigns/:permalink
GET /priv/v2/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_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 for Get a Specific Campaign for a Customer by ID and Either Campaign Permalink or ID

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

Request Object for Get a Specific Campaign for a Customer by ID and Either Campaign Permalink or ID

Not applicable.

Response Object for Get a Specific Campaign for a Customer by ID and Either Campaign Permalink or ID

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

JSON Response

{
  "behaviors": {
    "super user 12": {
      "event_name": "Event 12",
      "type": "count",
      "points": 5,
      "max_times_repeatable": null,
      "max_times_repeatable_per_period": 1,
      "period": 86400,
      "min_time_between_events": null,
      "consecutive": false,
      "achieved": 0,
      "current_count": 0,
      "total_count": 1
    },
    "participation challenge": {
      "event_name": "entry",
      "type": "count",
      "points": 0,
      "max_times_repeatable": 1,
      "max_times_repeatable_per_period": 1,
      "period": 7776000,
      "min_time_between_events": null,
      "consecutive": false,
      "achieved": 0,
      "current_count": 0,
      "total_count": 1
    }
  },
  "campaign_id": 16,
  "campaign_permalink": "d615678c-d458-11e7-8ac1-c27a328254fd",
  "ends_at": "2017-12-01 16:26:09",
  "name": "Campaign 16",
  "offers": [
  {
    "offer_id": 1,
    "name": "Offer 1 gift card",
    "type": "deal",
    "total_available": 100,
    "deal": {
      "percent": 10.0,
      "offer_type_id": "percent_discount",
      "id": "0c7af47e-12ef-4474-a0b7-3540948783bb",
      "root_offer_id": "d616c71c-d458-11e7-9903-c0c9328254fd",
      "retailer_id": "d616ee2c-d458-11e7-9d46-e185377754fd",
      "offer_text": [
        {
          "id": "0c7af47e-12ef-4474-a0b7-3540948783bb",
          "offer_id": "ff4b3d3c-8185-48b7-8014-dd03c2c55864",
          "culture": "en",
          "title": "Test for Offer796899",
          "description": "Testing Issue Offer",
          "terms": "Don't panic!"
        }
      ],
      "valid_after_end_date": true,
      "value_after_end_date": null,
      "start_date": "2017-11-28T16:26:10+0000",
      "end_date": "2017-11-29T16:26:10+0000",
      "validity_period": 1,
      "validity_unit": "day",
      "points": 200,
      "buy_count": 0,
      "max_recurrence": 1,
      "item_price_affinity": 0,
      "web_redeem": false,
      "quantity": 0,
      "reward_store": false,
      "offer_catalog_restrictions": null,
      "offer_purchase_restrictions": null,
      "offer_redemption_restrictions": null,
      "offer_location_restrictions": null,
      "offer_media": [
        {
          "id": "d617153c-d458-11e7-9ad9-8d08328254fd",
          "uri": "http://www.example.com",
          "category_id": "d617153c-d458-11e7-9ad9-8d08328254fd",
          "category_name": null,
          "content_type": 1,
          "culture": "en"
        }
      ]
    }
  },
  {
    "offer_id": 2,
    "name": "referrer points",
    "type": "trigger",
    "total_available": 1000000000
  }
],
  "opt_in_ends_at": "2017-12-01 16:26:09",
  "opt_in_starts_at": "2017-11-27 16:26:09",
  "qualified": true,
  "starts_at": "2017-11-27 16:26:09",
  "status": "qualified"
}

This object is detailed in the following tables:

Response Attributes for Behaviors

Response Attributes for Campaigns

Response Attributes for Offers

Response Attributes for Deal

Response Attributes for Offer Text

Response Attributes for Offer Media

Statuses and Errors for Get a Specific Campaign for a Customer by ID and Either Campaign Permalink or ID

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.

Implementation Notes for Retrieving Campaigns Using V2 APIs

As you work with any of the V2 endpoints that get campaigns 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 show and index routes: /dev/core1/app/controllers/priv/v2/users/campaigns_controller.rb (edited)

Endpoints that show and index 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" sections of Get all active campaigns eligible for a customer, Get a specific campaign for a customer by internal user ID and campaign ID, and Get a specific campaign for a customer by ID and either campaign permalink or ID.

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'

Retrieving Campaigns

This family of APIs allows you to:

• Get All Active Campaigns
• Get Information on a Specific Campaign

Get All Active Campaigns

Fetches all active campaigns within a specific platform implementation without having to provide any user-specific data.

Endpoints for Get All Active Campaigns

This method offers the following endpoint:

REST Endpoint

GET /v1/apps/:api_key/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 for Get All Active Campaigns

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

Request Object for Get All Active Campaigns

Not applicable.

Response Object for Get All Active Campaigns

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

JSON Response

{
  "status": "ok",
  "campaigns": [
    {
      "id": 367,
      "external_id": "cc8b6c38-b5c8-11e7-9082-dc7a60cca317",
      "name": "Campaign Example",
      "starts_at": "2017-10-01T18:59:00Z",
      "ends_at": "2018-02-28T19:59:00Z",
      "status": "draft",
      "weight": 5,
      "total_budget": 0,
      "ssap_name": "10/20 test 11",
      "reporting_ends_at": "2018-04-14T18:59:00Z",
      "campaign_type": "messaging",
      "metadata": {"campaign_version": 2},
      "template": "messaging",
      "targeting": {
        "$and": [
          {
            "user.tags": {
              "$in": ["my_tag_to_target_user"]
            }
          },
          {
            "user.tags": {
              "$not": {
                "$in": ["my_tag_to_target_away_from_user"]
              }
            }
          }
        ]
      },
      "qualify_tag": "my_tag_to_target_user",
      "disqualify_tag": "my_tag_to_target_away_from_user"
    }
  ]
}

This object is detailed in Response Attributes for Campaign table.

Statuses and Errors for Get All Active Campaigns

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 Information on a Specific Campaign

Fetches a specific campaign within a platform implementation, including its associated information without having to provide any user-specific data. Individual campaigns can be specified using either the campaign_id or permalink parameters.

Endpoints for Get Information on a Specific Campaign

This method offers the following endpoints:

REST Endpoints

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

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 for Get Information on a Specific Campaign

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

Request Object for Get Information on a Specific Campaign

Not applicable.

Response Object for Get Information on a Specific Campaign

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

JSON Response

{
  "status": "ok",
  "campaign":
  {
    "campaign_id": 1,
    "permalink": "my_flock_to_unlock_campaign",
    "starts_at": "2017-05-09 17:36:48",
    "ends_at": "2017-05-13 17:36:48",
    "optin_required": true,
    "opt_in_starts_at": "2017-05-09 17:36:48",
    "opt_in_ends_at": "2017-05-13 17:36:48"
  }
}

This object is detailed in the following tables:

Response Attributes for Campaign

Statuses and Errors for Get Information on a Specific Campaign

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.