Unica Campaign REST API

Use the Unica Campaign REST API to manipulate campaigns, offers, offer lists, attributes, and target cell objects.

Overview

The API is based on REST (Representational State Transfer) principles, so you can easily write and test applications. You can use your browser to access URLs, and you can use any standard HTTP client in any programming language to interact with the API. All API calls must be entirely lowercase.

Base URL

The base URL is: http://<host>:<port>/Campaign/api/campaign/rest

Prepend the base URL to each API that is listed. For example: http://host:port/Campaign/api/campaign/rest/v1/offers

List of APIs

Table 1. REST APIs for Campaign
Attributes
get: /v1/attributes Returns the metadata of all defined attributes or of the specified attribute.
post: /v1/attributes/create/{type} Creates attribute metadata for the specified object type.
delete: /v1/attributes/delete Deletes the metadata of the specified attribute.
get: /v1/attributes/metadata/{type} Returns the metadata for all attributes of the specified type or of the specified attribute.
put: /v1/attributes/update/metadata Updates the attribute values for a specified object.
put: /v1/attributes/update/{type}/{id} Updates the attribute values for a specified object Returns the metadata for the specified attributes.
get: /v1/attributes/{type}/{id} Returns the metadata for the specified attributes
Campaigns
get: /v1/campaigns Returns the list of Unica Campaign objects in the form of JSON data.
post: /v1/campaigns Creates a campaign with the provided JSON data.
get: /v1/campaigns/code Generates a Campaign code.
post: /v1/campaigns/delete Deletes the specified campaigns.
get: /v1/campaigns/metrics Returns the metrics for the specified campaign.
post: /v1/campaigns/search Search for campaigns based on the provided information.
get: /v1/campaigns/{campaignid} Returns the specified campaign object.
put: /v1/campaigns/{campaignid} Updates the specified campaign object.
delete: /v1/campaigns/{campaignid} Deletes the specified campaign object.
Offers
post: /v1/offers Creates one or more offers
post: /v1/offers/delete Deletes one or more offers
get: /v1/offers/gencode Generates one or more unique offer codes
post: /v1/offers/getoffers Lists all offer objects
post: /v1/offers/retire Retires one or more offers
post: /v1/offers/templates Returns a list with offer template details
post: /v1/offers/validate Checks to see if only one matching offer exists
Offers v2
post: /v2/offers Creates one or more offers
post: /v2/offers/delete Deletes one or more offers
get: /v2/offers/gencode Generates one or more unique offer codes
post: /v2/offers/getoffers Lists all offer objects
post: /v2/offers/retire Retires one or more offers
post: /v2/offers/templates Returns a list with offer template details
post: /v2/offers/validate Checks to see if only one matching offer exists
get: /v2/offers/search Returns a list of details of offers.
get: /v2/offers
Offer lists
get: /v1/offerlist Returns the list of OfferLists
put: /v1/offerlist Updates the OfferList
post: /v1/offerlist Creates OfferList
post: /v1/offerlist/createSmartOffer Creates smart OfferList
post: /v1/offerlist/delete Deletes OfferLists
post: /v1/offerlist/retire Retires OfferLists
Target cell objects
get: /v1/targetcells Returns the list of targetcells for the specified campaignid.
post: /v1/targetcells Creates a targetcell with the provided information.
post: /v1/targetcells/delete Bulk deletes the specified targetcells.
get: /v1/targetcells/runresults Returns the run results for the specified targetcells.
put: /v1/targetcells/update Updates an existing targetcell with the provided information.
delete: /v1/targetcells/{cellid} Deletes the specified targetcell.

HTTP Status Codes

The Unica Campaign REST API attempts to return appropriate HTTP status codes for every request. For example:

200 - OK
400 - Bad Request (Fix the error before resubmitting.)
500 - Internal Server Error (Check <Campaign_home>/logs/campaignweb.log on the Campaign web application server for details.)
404 - Not Found

Many online resources provide information about HTTP status codes.

Security framework for Unica APIs

Unica Platform provides the security framework for the APIs implemented by Unica products.

A set of configuration properties on the Settings > Configuration page enables developers to set the following security for the APIs provided by Unica products.

  • For a specific product API, you can block access to the product.
  • For a specific product API, you can require HTTPS for communication between the specified API and the product.
  • For a specific product API, you can require authentication for communication between the specified API and the product.

The configuration properties that control API security are located under the Unica Platform | Security | API management category. Each product has a configuration property template that you can use to create new security settings for the APIs provided by that product.

You can set and change the security settings for an API as appropriate for unit testing or deployment or during the overall lifecycle of APIs.

The security framework currently supports APIs for Unica Campaign only.

The Unica Platform security framework supports the following two authentication options for accessing protected APIs. You can use either one, depending on your environment.

  • Internal users who are registered with Unica Platform can be authenticated using their Unica Platform login credentials to obtain a secure token.
  • External users who are part of a federation that Unica Platform is set up to use can be authenticated though the Identity Provider server.

Internal user authentication with the Unica Platform login API

To authenticate internal users in client applications, use the Unica Platform login API to generate secure tokens. You can then invoke any protected APIs by passing the required parameters in the request header, in addition to the parameters expected by the API itself.

The security filter intercepts these protected requests, validates them, and then passes them through for processing.

After the Unica Platform user is authenticated, the Unica Platform security filter adds the user's login name to the request as an attribute of the USER_NAME_STRING key before passing it to the product for processing.

The secure tokens have a default life span of 15 seconds. After the life span of the token expires, it cannot be used to invoke a protected API. Each time the Unica Platform login API is invoked for a user, all previous security tokens for that user are invalidated.

You can change the life span of secure tokens by setting the value of the Token lifetime property located on the Settings > Configuration page under the General | Miscellaneous category.

Example URL

http[s]://host:port/unica/api/manager/authentication/login/

Header parameters

Table 2. Header parameters for the login API with internal users
Parameter Description
m_user_name The internal user's Unica Platform login name.
m_user_password The internal user's Unica Platform password in plain text.

Response

When login succeeds, the response is HTTP 200 with the following JSON data.

  • m_tokenId - randomly generated token
  • m_user_name - user name of the logged in user
  • createDate - timestamp in the format that is shown in the following example, where the time zone is IST:

    Mon Jul 06 18:23:35 IST 2015

When login fails with bad credentials, the response is HTTP 401 (unauthorized). When the login API is configured to be blocked, the response is 403 (forbidden). When the login API is configured to use HTTPS and if it is invoked on HTTP, the response is 403 (forbidden).

To log out internal users, use the Unica Platform logout API.

Internal user logout with the Unica Platform logout API

Use the Unica Platform logout API to log out internal users and delete the secure token.

The logout API is protected by default. The authentication parameters are expected in the request header against pre-defined keys.

Example URL

http[s]://host:port/unica/api/manager/authentication/logout/

Header parameters

Table 3. Header parameters for the logout API
Parameter Description
m_user_name The internal user's Unica Platform login name.
m_tokenId The secure token obtained through authentication.
api_auth_mode Use the value manager for internal users.

Response

When authentication succeeds, the response is HTTP 200, and the secure token is deleted. If the response is HTTP 200, the client application should confirm the logout.

When authentication fails, the response is HTTP 401.

External user authentication and logout through a federation

When Unica Platform is integrated with a supported federation, users can log in to their own system, and the client application gets a token through the Identity Provider (IdP) server provided by Unica Platform.

After a federated user is authenticated, their corresponding Unica Platform login name is added to the request as an attribute of the USER_NAME_STRING key.

Log out should be done at the IdP server.

Header parameters

The following table describes the header parameters to use when authenticating through the IdP server provided by Unica Platform.

Table 4. Header parameters with a federation
Parameter Description
f_userId User ID in the federation.
f_clientId Client ID in the federation.
f_spId Service provider ID in the federation.
f_tokenId Single sign-on token from the IdP server.
api_auth_mode Use the value fsso for federated authentication.

Response

The response is HTTP 200, with additional items depending on the API.