Campaign REST API-V1 and V2

Unica Campaign is an advanced campaign management solution that brings with it the powerful segmentation capabilities of outbound, multi-channel, multi-wave batch campaign execution, and tracking. But how does everything operate in the background, how does the Campaign connect or integrate with the other products in the suite? There is a restful approach of doing it. Yes, we are talking about the REST APIs. So what is REST APIs, and how are they used in creating Campaign objects is a question which has multiple aspects and areas. The HCL Campaign REST API to manipulate campaigns, offers, offer lists, attributes, and target cell objects.

What are REST APIs?

You are trying to search and book your flights on the internet, and in a few seconds, you have the results. That is the function an API performs, helping two systems talk to each other. REST is an approach that facilitates such communications by assisting in creating APIs keeping a specific set of rules in mind.

I work as a Unica Support Engineer and a Client Advocate, and I come across many different Unica use cases and questions. One thing I have observed is that while using REST API calls to create campaign objects, people struggle to do configurations required in the Platform. The challenges can vary, like using the sample JSON body, parameters needed to execute API calls, or updating the configuration values for any version of REST APIs. This article focuses and helps to understand and perform configurations in Platform. To execute REST API calls, we use the Postman tool as it’s been used by most of the users and our clients while working with REST API calls.

Configurations at Platform Side

1. Increase a token’s lifetime, which is used for authentication in API calls.

– Navigate to: Affinium|Manager|miscellaneous.

– Increase Token Lifetime value as needed. It’s in seconds.

2. Change configurations for API authentication.

– Navigate to Affinium|suite|security|apiSecurity|manager|managerAuthentication

– Disable all properties.

– If you want to keep ‘require authentication for API access’ as true, it will validate the password for users used for API calls.

– Assign some password for users from Settings >Users. If it’s disabled, you don’t need to pass any password.

3. Navigate to Affinium|suite|security|apiSecurity|manager|Logout and change configuration value as below.

4. Update configurations for Rest API Ver 1.0

– Navigate to Affinium|suite|security|apiSecurity|campaign|Campaign REST API V2 Filter.

– Update configuration values. Refer to the below screenshot.

– Restart the application server.

Postman tool to execute API calls.

Postman is a software development tool. It enables people to test calls to APIs. Postman users enter data. The data is sent to a special web server address. Typically, information is returned, which Postman presents to the user. Although you can use any tool. The main aim is to provide the necessary details while we are trying to make an API call. There are parameters like call types, request parameters (header, body), and the URL which are required for execution.

1. Execute POST API call to Platform to get token, which can be used in subsequence API calls for authentication.

Call: POST
URL : https://<HostName:Port>/unica/api/manager/authentication/login/
Headers :
M_user_name > user used for API calls for e.g. asm_admin
M_user_password > password set for user.

2. You can use this token ID for posting any API calls for Campaign rest APIs. List down offers- 

Call: GET
URL : https://<HostName:Port>/ Campaign/api/campaign/rest/v2/offers/search?search
Headers :
m_user_name  > asm_admin
m_tokenid         > <TokenID captured in platform post call>
api_auth_mode > manager

In the ‘search’ string, you can pass any string value to search specific offers.

REST V2 example

List the particular offer details.

Call: GET
URL : https://<hostname:port>/Campaign/api/campaign/rest/v2/offers/29
Where 29 is offerID . Pass any offer ID for which you need to fetch the details.
Headers :
m_user_name > asm_admin
m_tokenid > <TokenID captured in platform post call>
api_auth_mode > manager

Response :

How to create offers in Campaign?

Call: POST
URL : https://<HostName:Port>/Campaign/api/campaign/rest/v2/offers

• Headers :

  m_user_name > asm_admin
  m_tokenid > <TokenID captured in platform post call>
  api_auth_mode > manager
  Content-Type > application/json

• In query parameters, pass below values :
  securityPolicy: Policy name for e.g., ‘Global Policy.’
  folderid: folder ID under which we need to create offers for e.g., 4 [root folder for offers]
  templateName: campaign offerTemplate name from which offers to be created.
• Body :
  Select the raw radio button and send JSON body.
  It will have the offer name and parameters. If not, parameters passed; it will create an offer with the default parameter value.

   

  [ {
  "offerName":"RESTNewOffer_IP1",
  "attributes":[]
  } ]

REST V1 Example

How to execute v1 rest APIs for campaign offer creation?

• All configuration steps are the same as defined before.
• Fetch platform tokenID with the same steps.
• The only difference is with the data input type we need to pass in API calls.
  In v2, we observed we are passing input data as raw JSON.
  For v1, we need to pass all parameters as ‘x-www-form-urlencoded’.
  Call: POST
  URL : https://<HostName:Port>/Campaign/api/campaign/rest/v1/offers

Headers :

m_user_name > asm_admin
m_tokenid > <TokenID captured in platform post call>
api_auth_mode > manager

You don’t need to add content type, it will be automatically picked up with the input type we are going to select.

On-body section,the select radio button for ‘x-www-form-urlencoded’, pass the below values.

securityPolicy: Policy name for e.g. ‘Global Policy’
folderid: folder ID under which we need to create offers for e.g. 4 [root folder for offers]
templateName: campaign offerTemplate name from which offers to be created .
BulkOfferInfo : [{"offerName":"Offer API","attributes":[]}]

It will have the offer name and parameters. If not parameters passed, it would create an offer with the default parameter value. You can refer below the screenshot for request and response.

If we want to pass, offer parameters, update your request body by adding parameter values as needed :

BulkOfferInfo:
[
{"offerName":"Offer Interact API_3",
"attributes":[
{"type":"TextAttribute","name":"ABC_TXT","value":"XYZ"},
{"type":"DecimalAttribute","name":"UACIInteractionPointID","value":2.0},
{"type":"TextAttribute","name":"UACIInteractionPointName","value":"IP2"}
]
}]

Campaign REST API calls facilitate users to carry out operations like create+update+delete+List on campaign objects (offers, creating campaigns) without login into the Unica Application. To learn more about how REST API works with Campaign you can reach out to us.