Individual API

Introduction

This document describes the Individual API. This API is implemented as a SOAP Web service that can be installed on the Application Server. Its location is always:  http://domainname/automation/individual.asmx

This Web Service is directly related to the “Gate” component which can be created / configured in the Campaign Configuration section. Basically, a Gate is an entry point to the Campaign environment used by the individual API.

Functional description

The Individual API provides various functions allowing the management of user profiles through the API.

Available actions:

Parameter types used in the API

Note: It is recommended to, whenever date information needs to be passed, use the following format: yyyyMMdd to ensure that dates are passed in a consistent way.

Automation User

To use the web service, it’s mandatory to create an ‘automation’ user in the Campaign configuration section. It is this user that will be used for authentication in the API calls.

To do so, go to User/Group Management and create a new user, give it a name and password and only rights to “automation”:

Individual API functions overview

Searching contacts: GetUsersByFilter

Description: Retrieve a list of contacts based on a filter.

Function prototype

int GetUsersByFilter(int List, Property[] Filter, int MaxCount, out int[] ResultIDs, out string ErrorStr)

Input parameters:

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password

// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsIn = new Individual_API.Property[1];
int SoapResult;
string errorStr;
int[] results;
Individual_API.Property optout = new Individual_API.Property();
optout.Key = "OPTOUT";
optout.Value ="1";
propsIn[0] = optout;

// Function call
SoapResult = ind.GetUsersByFilter("147", propsIn, 5, out results, out errorStr);
Response.Write("User_IDs with an OPTOUT set to 1 : ");
for (int i = 0; i < results.Count(); i++)
    Response.Write(results[i].ToString() + " " );

Result:

Note: The function GetUserByFilter only retrieves one specific contact. The parameters are the same, except for the MaxCount, which is obsolete.

Searching contacts: GetUsersByConstraint

Description: Retrieve a list of contacts based on a constraint.

Function prototype

int GetUsersByConstraint(int List, string Constraint, int MaxCount, out int[] ResultIDs, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password

// IMPORTANT : This user is created in the SELLIGENT <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";

ind.AutomationAuthHeaderValue = header;

// Variables
int SoapResult;
int[] results;
string errorStr;

// Function call
SoapResult = ind.GetUsersByConstraint("147", "MAIL LIKE '%@selligent.com%'", 5, out results, out errorStr);
Response.Write("GetUsersByConstraint - List of User_IDs: ");
for (int i = 0; i < results.Count(); i++)
    Response.Write(results[i].ToString() + " ");

Result:

Note: The function GetUserByConstraint only retrieves one specific contact. The parameters are the same, except for the MaxCount, which is obsolete.

Retrieving profile properties: GetUserByFilter

Description: Retrieve contact information based on a filter

Function prototype

int GetUserByFilter(int List, string Constraint, out Property[] ResultSet, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password

// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsIn = new Individual_API.Property[1];
Individual_API.Property[] propsOut = new Individual_API.Property[0];
int SoapResult, iUserID;
string errorStr;
Individual_API.Property optout = new Individual_API.Property();
optout.Key = "MAIL";
optout.Value ="test@selligent.com";
propsIn[0] = optout;

// Function call
SoapResult = ind.GetUserByFilter("147", propsIn, out propsOut, out errorStr);
iUserID = Convert.ToInt32("0" + propsOut[0].Value);
for (int i = 0; i < propsOut.Count(); i++)
        Response.Write(propsOut[i].Key.ToString() + " : " + propsOut[i].Value.ToString() + "<br/> ");

Result:

Retrieving profile properties: GetUserByConstraint

Description: Retrieve user information based on a constraint.

Function prototype

int GetUserByConstraint(int List, string Constraint, out Property[] ResultSet, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsOut = new Individual_API.Property[0];
int SoapResult;string errorStr;

// Function call
SoapResult = ind.GetUserByConstraint("147", "MAIL = 'test@selligent.com'", out propsOut, out errorStr);
Response.Write("GetUserByConstraint - List of Properties: <br/>");
for (int i = 0; i < propsOut.Count(); i++)
        Response.Write(propsOut[i].Key.ToString() + " : " + propsOut[i].Value.ToString() + "<br/> ");

Result:

Retrieving profile properties: GetUserById

Description: Retrieve contact information based on a user ID.

Function prototype

int GetUserByID(int List, int UserID, out Property[] ResultSet, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsOut = new Individual_API.Property[0];
int SoapResult, iUserID;string errorStr;

// Function call
SoapResult = ind.GetUserByID("147",2,out propsOut, out errorStr);
iUserID = Convert.ToInt32("0" + propsOut[0].Value);
for (int i = 0; i < propsOut.Count(); i++)
        Response.Write(propsOut[i].Key.ToString() + " : " + propsOut[i].Value.ToString() + "<br/> ");

Result:

Create / Update contact: CreateUser

Description: Create a contact in the specified list.

Function prototype

int CreateUser(int List, Property[] Changes, out int ID, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsIn = new Individual_API.Property[2];
int SoapResult, iUserID;
string errorStr;

Individual_API.Property optout = new Individual_API.Property();
optout.Key = "MAIL";
optout.Value = "test@selligent.com";
propsIn[0] = optout;

Individual_API.Property name = new Individual_API.Property();
name.Key = "NAME";
name.Value = "MyUser";
propsIn[1] = name;

// Function call
SoapResult = ind.CreateUser("147", propsIn, out iUserID, out errorStr);
        Response.Write("ID of the new user : " + iUserID);

Result:

Create / Update contact: UpdateUser

Description: Update a contact profile in the specified list.

Function prototype

int UpdateUser(int List, int UserID, Property[] Changes, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsIn = new Individual_API.Property[2];
int SoapResult;
string errorStr;
Individual_API.Property optout = new Individual_API.Property();
optout.Key = "MAIL";
optout.Value = "test_modified@selligent.com";
propsIn[0] = optout;
Individual_API.Property name = new Individual_API.Property();
name.Key = "NAME";
name.Value = "MyUser";
propsIn[1] = name;

// Function call
SoapResult = ind.UpdateUser("147",6,propsIn, out errorStr);

Create / Update contact: UpdateUsers

Description: Update multiple contact profiles in the specified list.

Function prototype

int UpdateUsers(int List, UserChanges[] changes, int mode, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Counting contacts: CountUsersByFilter

Description: Count the number of contacts based on a filter.

Function prototype

int CountUsersByFilter(string List, Property[] Filter, out int userCount, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

// Create the service
AutomationIndividual.Individual service = new AutomationIndividual.Individual();

// Defining login and password
// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> Configuration and has only access to Individual API
AutomationIndividual.AutomationAuthHeader authenticationHeaderValue = new AutomationIndividual.AutomationAuthHeader() {
    Login = "MyUser",Password = "MyPassword"
};
service.AutomationAuthHeaderValue = authenticationHeaderValue;

// Variables
int userCount;
string errorString;
AutomationIndividual.Property[] filters = new AutomationIndividual.Property[] {
    new AutomationIndividual.Property {
        Key = "FIRSTNAME", Value = "Emelda"
    }
};

// Function call
int errorCode = service.CountUsersByFilter("173", filters, out userCount, out errorString);

//Print output
Console.WriteLine("errorCode: {0} - errorString: {1} - userCount: {2}", errorCode, errorString, userCount);

Result: errorCode: 0 - errorString: - userCount: 5

Counting contacts: CountUsersByConstraint

Description: Count the number of contacts based on a constraint.

Function prototype

int CountUsersByConstraint(string List, string Constraint, out int userCount, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

// Create the service
AutomationIndividual.Individual service = new AutomationIndividual.Individual();

// Defining login and password
// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
AutomationIndividual.AutomationAuthHeader authenticationHeaderValue = new AutomationIndividual.AutomationAuthHeader() {
    Login = "MyUser",Password = "MyPassword"
};
service.AutomationAuthHeaderValue = authenticationHeaderValue;

// Variables
int userCount;
string errorString;

// Function call
int errorCode = service.CountUsersByConstraint("173", "FIRSTNAME = 'Emelda'", out userCount, out errorString);

//Print output
Console.WriteLine("errorCode: {0} - errorString: {1} - userCount: {2}", errorCode, errorString, userCount);

Result: errorCode: 0 - errorString: - userCount: 5

Retrieve Hash: RetrieveHashForUser

Description: Retrieve the hash code for the selected contact.

Function prototype

int RetrieveHashForUser(string GateName, string List, int UserID, out string HashCode, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> Configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsOut = new Individual_API.Property[0];
int SoapResult, iUserID;
string errorStr;

// Function call
SoapResult = ind.GetUserByConstraint("162", "MAIL=MyEmail@selligent.com'", out propsOut, out errorStr);
iUserID = Convert.ToInt32("0" + propsOut[0].Value);

// RetrieveHashForUser
String MAHash;
SoapResult = ind.RetrieveHashForUser("INDIVIDUAL_API", "162", iUserID, out MAHash, out errorStr);
Response.Write("RetrieveHashForUser :" + MAHash);

Result:

Manage contacts: GetUsersXmlByConstraint

Description: gets the contacts for a given list applying the constraint as a filter

Function prototype:

int GetUsersXmlByConstraint(string List, string Constraint, out string Xml, out string ErrorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 when successful.

Journey map Management: TriggerCampaign

Description: Trigger the execution of the specified journey map.

Function prototype

int TriggerCampaign(string GateName, Property[] InputData, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsIn = new Individual_API.Property[2];
int SoapResult;
string errorStr;
Individual_API.Property mail = new Individual_API.Property();
mail.Key = "MAIL";
mail.Value = "me@selligent.com";
propsIn[0] = mail;
Individual_API.Property name = new Individual_API.Property();
name.Key = "NAME";
name.Value = "MyName";
propsIn[1] = name;

// Function call
SoapResult = ind.TriggerCampaign("DEMOTRIGGERCAMPAIGN", propsIn, out errorStr);

Result: 0

Journey map Management: TriggerCampaignWithResult

Description: Trigger the execution of the specified journey map and returns the result

Function prototype

int TriggerCampaignWithResult(string GateName, Property[] InputData, out string result, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsIn = new Individual_API.Property[2];
int SoapResult;
string errorStr;
string result;
Individual_API.Property mail = new Individual_API.Property();
mail.Key = "MAIL";
mail.Value = "me@selligent.com";
propsIn[0] = mail;
Individual_API.Property name = new Individual_API.Property();
name.Key = "NAME";
name.Value = "MyName";
propsIn[1] = name;

// Function call
SoapResult = ind.TriggerCampaignWihResult("DEMOTRIGGERCAMPAIGN", propsIn, out result, out errorStr);

Result: 0

Journey map Management: TriggerCampaignByXml

Description: Trigger the execution of the specified journey map.

Function prototype

int TriggerCampaignByXml(string GateName, string Xml, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
string myXML = "<XML><MAIL>me@selligent.com</MAIL><NAME>MyName</NAME></XML>";
int SoapResult;
string errorStr;

// Function call
SoapResult = ind.TriggerCampaignByXml("DEMOTRIGGERCAMPAIGN", myXml, out errorStr);

Result: 0

Remarks: This is the same as the previous function ‘TriggerCampaign’ but input is provided through XML.

Journey map Management: TriggerCampaignByXmlWithResult

Description: Trigger the execution of the specified journey map.

Function prototype

int TriggerCampaignByXmlWithResult(string GateName, string Xml, out string result, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
string myXML = "<XML><MAIL>me@selligent.com</MAIL><NAME>MyName</NAME></XML>";
int SoapResult;
string errorStr;
string result;

// Function call
SoapResult = ind.TriggerCampaignByXmlWithResult("DEMOTRIGGERCAMPAIGN", myXml, out result ,out errorStr);

Result: 0

Remarks: This is the same as the previous function ‘TriggerCampaign’ but input is provided through XML.

Journey map Management: TriggerCampaignForUser

Description: Trigger the execution of the specified journey map for a specific contact.

Function prototype

int TriggerCampaignForUser(int List, int UserID, string GateName, Property[] InputData, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsIn = new Individual_API.Property[1];
Individual_API.Property mail = new Individual_API.Property();
mail.Key = "MAIL";
mail.Value = "me@selligent.com";
propsIn[0] = mail;

// Function call
SoapResult = ind.TriggerCampaignForUser("147", "3", "DEMOFORGOTPWDEXT", propsIn, out errorStr);

Result: 0

Remarks: A journey map should first be set up.

Journey map Management: TriggerCampaignForUserWithResult

Description: Trigger the execution of the specified journey map for a specific contact.

Function prototype

int TriggerCampaignForUserWithResult(int List, int UserID, string GateName, Property[] InputData, out string result, out string ErrorStr)

Input parameters

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Variables
Individual_API.Property[] propsIn = new Individual_API.Property[1];
String result;
Individual_API.Property mail = new Individual_API.Property();
mail.Key = "MAIL";
mail.Value = "me@selligent.com";
propsIn[0] = mail;

// Function call
SoapResult = ind.TriggerCampaignForUserWithResult("147", "3", "DEMOFORGOTPWDEXT", propsIn, out result , out errorStr);

Result: 0

Remarks: A journey map should first be set up.

Journey map Management: TriggerCampaignForUserAndActionListItem

Description: Triggers a campaign for a specific contact using a specific action list record.

Function prototype:

int TriggerCampaignForUserAndActionListItem(int ListID, int ActionListID, int UserID, string GateName, string ActionCode, Property[] ActionListItemData, out string ErrorStr)

Input parameters

Output parameters

individual2.IndividualSoapClient client= new individual2.IndividualSoapClient();
individual2.AutomationAuthHeader header= new individual2.AutomationAuthHeader();
header.Login = "Automation_action";
header.Password = "1234abcd";
individual2.Property [] p = new individual2.Property[1];
p[0] = new individual2.Property();
p[0].Key = "PRICE";
p[0].Value = "789789";
int result = client.TriggerCampaignForUserAndActionListItem(header, 237,238,1,"IND_ACTION", "TEST", p, out errorStr);

Journey map Management: TriggerCampaignForUserAndActionListItemWithResult

Description: Triggers a campaign for a specific contact using a specific action list record.

Function prototype:

int TriggerCampaignForUserAndActionListItemWithResult(int ListID, int ActionListID, int UserID, string GateName, string ActionCode, Property[] ActionListItemData, out string result, out string ErrorStr)

Input parameters

Output parameters

individual2.IndividualSoapClient client= new individual2.IndividualSoapClient();
individual2.AutomationAuthHeader header= new individual2.AutomationAuthHeader();
header.Login = "Automation_action";
header.Password = "1234abcd";
string result;
individual2.Property [] p = new individual2.Property[1];
p[0] = new individual2.Property();
p[0].Key = "PRICE";
p[0].Value = "789789";
int result = client.TriggerCampaignForUserAndActionListItemWithResult(header, 237,238,1,"IND_ACTION", "TEST", p, out result, out errorStr);

Journey map Management: GetPlannedCampaigns

Description: Gets the campaigns that are scheduled to run

Function prototype:

int GetPlannedCampaigns(out PlannedCampaignInfo[] plannedCampaigns, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful.

System Information: GetSystemStatus

Description: Provides information about the current status of the system.

Function prototype

string GetSystemStatus(out string ErrorStr)

Output parameters

Returned value: Returns 0 if the execution is successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
// IMPORTANT : This user is created in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword";
ind.AutomationAuthHeaderValue = header;

// Function call
string errorStr;
Response.Write("System Status : " + ind.GetSystemStatus(out errorStr));

Result:

Manage Segments: CreateSegment

Description: Creates a new static segment for a user list

Function prototype:

int CreateSegment(int listid, string name, string description, out int segmentId, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if the creation was successful. There is no error description in that case but a segment id is returned.

In case the operation is not successful:

• 10001: ERROR_OBJECTSTORE

• 10006: ERROR_FAILED

• 10002: ERROR_LIST

• 10006: ERROR_FAILED

• 10003: ERROR_QUERY

Manage Segments: AddToSegment

Description: Adds a list of ID’s to a segment

Function prototype:

int AddToSegment(int segmentid, int[] ids, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns a number. 0 in case the operation was successful. In case it was not successful:

• 10006: ERROR_FAILED

• 10002: ERROR_LIST

• 10006: ERROR_FAILED

• 10003: ERROR_QUERY

• 10010: ERROR_SEGMENT_NOT_FOUND

If not successful an error is returned.

Manage Segments: GetSegmentRecordCount

Description: gets the amount of recipients in a segment

Function prototype:

int GetSegmentRecordCount(int segmentId, out int segmentCount, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 when successful.

Manage Segments: GetSegments

Description: gets the segments for a specific list

Function prototype:

int GetSegments(int listId, out SegmentInfo[] segments, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 when successful.

Manage Action Lists: AddActionCode

Description: Adds a new action code for an action list

Function prototype:

int AddActionCode (int actionListID, string code, string description, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful

Manage Action Lists: AddActionCodes

Description: Adds multiple action codes for an action list

Function prototype:

int AddActionCode (int actionListID, ActionCode[] codes, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful

Manage Action List: GetActionCodes

Description: Retrieves the action codes for an action list

Function prototype:

int GetActionCodes (int actionListID, out ActionCode[] codes, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful

Manage Action List: GetActionLists

Description: Returns an overview of all actions lists that are available.

Function prototype:

int GetActionLists (out ActionListInfo[] actionLists, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful

Manage Action Lists: AddRecordToActionList

Description: Adds a new record to an action list

Function prototype:

int AddRecordToActionList(int actionListID, Property[] data, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful

Manage Action Lists: AddRecordsToActionList

Description: Adds a batch of new records to an action list

Function prototype:

int AddRecordsToActionList(int actionListID, List<Property[]> data, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful

Individual_API.Individual ind = new Individual_API.Individual();
Individual_API.AutomationAuthHeader header = new Individual_API.AutomationAuthHeader();

// Defining login and password
// IMPORTANT : This user is created in the SELLIGENT Campaign configuration and has only access to Individual API
header.Login = "MyUser";
header.Password = "MyPassword$123";
ind.AutomationAuthHeaderValue = header;

// Variables
int SoapResult;
string errorStr;
Individual_API.Property[][] records = new Individual_API.Property[2][];
Individual_API.Property prop = new Individual_API.Property();

// RECORD 1
// * system-actionrecord-fields
prop.Key = "LISTID";
prop.Value = "1";
records[0][0] = prop;
prop.Key = "USERID";
prop.Value = "16";
records[0][1] = prop;
prop.Key = "ACTIONCODE";
prop.Value = "PURCHASE";
records[0][2] = prop;
// * Custom field
prop.Key = "MSG";
prop.Value = "Thank you for your order";
records[0][3] = prop;
prop.Key = "PRICE";
prop.Value = "156.65";
records[0][4] = prop;

// RECORD 2
// * system-actionrecord-fields
prop.Key = "LISTID";
prop.Value = "1";
records[1][0] = prop;
prop.Key = "USERID";
prop.Value = "22";
records[1][1] = prop;
prop.Key = "ACTIONCODE";
prop.Value = "REMINDER";
records[1][2] = prop;
// * Custom field
prop.Key = "MSG";
prop.Value = "is a reminder";
records[1][3] = prop;
prop.Key = "PRICE";
prop.Value = "16.23";
records[1][4] = prop;

// Function call
SoapResult = ind.AddRecordsToActionList(5, records, out errorStr);Response.Write("<h1>Result:</h1>" + SoapResult);
if (!string.IsNullOrEmpty(errorStr))
        Response.Write("<h1>Error:</h1>" + errorStr);

Manage Action Lists: CreateActionList

Description: creates a new action list

Function prototype:

int CreateActionList(string name, string description, FieldsDefinition[] additionalFields, out int actionListId, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful

Manage Lists: GetListID

Description: Get the id of a list by using its name

Function prototype:

int GetListID(string name, out int id, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful

Manage lists: GetLists

Description: retrieve a series of lists

Function prototype:

int GetLists(int[] ids, string constraint, out ListInfo[] lists, out string errorStr)

Input parameters

Output parameters:

Returned value:

Returns 0 if successful

Error codes

Below follows a summary of the possible error codes and their reason.

Using the Individual API (ASP.net / PHP)

This chapter presents two examples created to illustrate how it’s possible to use the Individual API to get information on a user and to trigger a journey map. The corresponding API functions are called “GetUserById” and “TriggerCampaign”.

Example 1: GetUserById

The GetUserById method allows retrieving user data based on its ID.

Calling the method with ASP.net

Adding the SOAP service

1. In an ASP.net web application, right click on the website project file in the solution explorer and choose “Add Web Reference…”

2. Put the URL of the individual API service of the installation in the URL field and press the green arrow.

3. Name the Web Reference (MyService in this example).

4. When done with the configuration, click on the “Add Reference” button to register the web service in your application.

From this point, the web service is accessible in the ASP.net website. In the solution explorer you can find the reference under the Web References folder, a section is also added in the “web.config” file for this service.

Now that the configuration is done, the usage of the web service can start.

Getting user information

Design the asp.net page. We need one textbox, one button, and a text area for displaying result.

The corresponding asp.net mark-up is:

Call the web service .

After the button click event, a call to the web service is done:

1. First step is to create an instance of the webservice

   MyService.Individual indu = new MyService.Individual();

2. Set the Automation header for authentication. This is the login and password for the automation user you defined in the Campaign configuration

   indu.AutomationAuthHeaderValue = new MyService.AutomationAuthHeader();
   indu.AutomationAuthHeaderValue.Login = "XXXXX";indu.AutomationAuthHeaderValue.Password = "XXXXX";

3. Create our input and Output parameters

    string error;
Property[] outProps = null;

4. Call the webservice -> XXX is the ID of the list

   int resultcode = indu.GetUserByID("XXX", int.Parse(txtUserId.Text), out outProps, out error);

5. Use the generated output:

   txtResponse.Text = "";
   if (outProps != null && outProps.Count() >= 1)
   {
   foreach (Property prop in outProps)
   {
   txtResponse.Text += prop.Key + ": \t" + prop.Value + "\n";
   }
   }

/// <summary>
/// Get a user by ID
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>

protected void btnUserById_Click(object sender, EventArgs e) {
    //1. Create service instance
    MyService.Individual indu = new MyService.Individual();
    
    //2. Set automationAuthHeader
    indu.AutomationAuthHeaderValue = new MyService.AutomationAuthHeader();
    indu.AutomationAuthHeaderValue.Login = "XXXXX";
    indu.AutomationAuthHeaderValue.Password = "XXXXX";
    
    //3. Create in/out props
    string error;
    Property[] outProps = null;
    
    //4. Call webservice method
    int resultcode = indu.GetUserByID("XXX", int.Parse(txtUserId.Text), out outProps, out error);
    
    //5. Loop props
    txtResponse.Text = "";
    if (outProps != null && outProps.Count() >= 1) {
        foreach (Property prop in outProps) {
            txtResponse.Text += prop.Key + ": \t" + prop.Value + "\n";
        }
    }
}

6. When done with your code, save it + build your solution (ctrl+shift+b) before testing it

   

Calling the method with PHP

Create the following PHP form:

The corresponding PHP mark-up code is :

<form action="getuser.php" method="post">
    <fieldset>
        <legend>Get user by ID</legend>
        <table>
            <tr>
                <td> UserID: </td>
                <td><input id="txtUserId" name="txtUserId" /></td>
            </tr>
        </table>
        <br />
        <input type="submit" id="btnGetUserById" name="btnGetUserById" value="Get user" />
        <br />
        <textarea id="txtResponse" rows="10" cols="50"><?php echo $outputgetuser; ?>
        </textarea>
    </fieldset>
</form>

A form tag has been added with an action to the same page and method to POST so we can use php $_POST[‘field’] to get the value of the input controls. In the text area we display the value of a php var $outputgetuser .

The PHP code

1. Set login and password.

   Copy

   $login = 'XXXXX';
   $password = 'XXXXX';

2. Create instance of the soapClient

   Copy

   $client = new soapclient("http:/domain_name/automation/individual.asmx?WSDL"); 

3. Set AutomationAuthHeader from web service

   Copy

   $header = new SoapHeader(
       'http://tempuri.org/',
       'AutomationAuthHeader',
       array(
           'Login' => $login,
           'Password' => $password,
       )
   );
   $client->__setSoapHeaders($header);

4. If form for GetUserByID is submitted

   Copy

   if ($_POST) {

5. Set variables to be used as parameters in web service call, XXX is the ID of the list

   Copy

   $userid = "";
   $userid = $_POST['txtUserId'];
   $listid = "XXX";

6. User id has to be filled in

   Copy

   if ($userid> 0 && $listid>0) {
       $input = array('List' => $listid,'UserID' => $userid);

7. Call the web service

   Copy

   $result = $client->GetUserByID($input, &$id, &$error);

8. Output: do something with the result, here we set the content of a text area

$outputgetuser;
$error = $result->ErrorStr;
$outputgetuser = $error;

if ($outputgetuser!='No user found') {
    foreach($result->ResultSet->Property as $d => $a) {
        $outputgetuser = $outputgetuser . $a->Key.": \t".$a->Value ."\n";
    }
} else {
    $outputgetuser = 'no ListID and/or UserId';
}

// set login and password
$login = 'XXXXX';
$password = 'XXXXX';

// create instance of the soapClient
$client = new soapclient("http://domain_name/automation/individual.asmx?WSDL");

// set AutomationAuthHeader from webservice
$header = new SoapHeader(
    'http://tempuri.org/',
    'AutomationAuthHeader',
    array('Login' => $login, 'Password' => $password)
);
$client->__setSoapHeaders($header);

// if form for GetUserByID is submitted
if ($_POST) {
    // set variables to be used as parameters in webservice call
    $userid = "";
    $userid = $_POST['txtUserId'];
    $listid = "XXX";
        
    // userid has to be filled in
    if ($userid> 0 && $listid>0) {
        $input = array('List' => $listid, 'UserID' => $userid);
        // call the webservice
        $result = $client->GetUserByID($input, &$id, &$error);
        
        // OUTPUT: do something with the result, here we set the content of a textarea
        $outputgetuser;
        $error = $result->ErrorStr;
        $outputgetuser = $error;        
        if($outputgetuser!='No user found') {
            foreach($result->ResultSet->Property as $d => $a) {
                $outputgetuser = $outputgetuser .  $a->Key.": \t".$a->Value ."\n";
            }
        } else {
            $outputgetuser = 'no ListID and/or UserId';
        }
    }
}

Example 2: TriggerCampaign

A journey map can be launched with the TriggerCampaign method. This function has to be provided with a gate name and all the values required by the targeted journey map.

Creating the Journey map

Create a simple journey map which updates or inserts a user:

The input component is set to “webservice” and defines 3 parameters for which we’ll pass the values using the TriggerCampaign method.

Because the input component is set to “webservice”, it’s not required to create a page after the data component. It will always return 0 (zero) if the journey map was executed successfully.

Note: In this example, even when the validation fails, it will still return 0 because the journey map was executed successfully. If you need more control on what is returned, set the input component back to “Weblink” and create 2 pages which return after the onFailed trigger data_error , and onSuccess “OK”. Just put in the onFailed page ~DATA_ERROR~ in the source code and “OK” in the onSuccess page.

Whatever is in the pages will be returned in the TriggerCampaign result. But the solution will output the pages with html content around it (head, body,…). So you’ll need to use an alternative content renderer which will only output the content of the page itself (explained in a separate document).

In the journey map properties>advanced you can define an alternative content renderer:

Defining the Gate

You need to create a gate in the Campaign configuration, the gate name you can use in your method. In the gate you can define which journey map has to be triggered. You can also limit the use to 1 list and activate logging on this gate. The use of the service will be logged on the server.

Calling the method with ASP.net

Adding the SOAP service

1. In an ASP.net web application, right click on the website project file in the solution explorer and choose “Add Web Reference…”

2. Put the URL of the individual API service of the Campaign installation in the URL field and press the green arrow.

3. Name the Web Reference (MyService in this example).

4. When done with the configuration click on the “Add Reference” button to register the web service in your application.

   

From this point, the web service is accessible in the ASP.net website. In the solution explorer you can find the reference under the Web References folder, a section is also added in the “web.config” file for this service.

Now that the configuration is done, the usage of the web service can start.

Triggering the journey map

1. Design the asp.net page as illustrated below:

The corresponding asp.net mark-up is:

Call the web service

2. After the button click event a call to the web service is done:

MyService.Individual indu = new MyService.Individual();

// Set automationAuthHeader
indu.AutomationAuthHeaderValue = new MyService.AutomationAuthHeader();
indu.AutomationAuthHeaderValue.Login = "XXXXX";
indu.AutomationAuthHeaderValue.Password = "XXXXX";

// Create in/out props, the keys are the parameters from the input component in the journey map
string error;
Property[] props = new Property[] {
    new Property() {
        Key = "FIRSTNAME", Value = txtFirstname.Text
    },
    new Property() {
        Key = "LASTNAME", Value = txtLastname.Text
    },
    new Property() {
        Key = "EMAIL", Value = txtEmail.Text
    }
}
    
// Call webservice method, "TEST" is the gate name defined in the <span class="mc-variable MyVariables.Campaign variable">Campaign</span> configuration
int resultcode = indu.TriggerCampaign("TEST", props, out error);

/// <summary>
/// Triggers a campaign in <span class="mc-variable MyVariables.Campaign variable">Campaign</span>
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>

protected void btnTriggerCampaign_Click (object sender, EventArgs e) {
    //1. Create service instance
    MyService.Individual indu = new MyService.Individual();
    
    //2. Set automationAuthHeader
    indu.AutomationAuthHeaderValue = new MyService.AutomationAuthHeader();
    indu.AutomationAuthHeaderValue.Login = "XXXXX";
    indu.AutomationAuthHeaderValue.Password = "XXXXX";
    
    //3. Create in/out props
    string error;
    Property[] props = new Property[] {
        new Property() {
            Key = "FIRSTNAME", Value = txtFirstname.Text
        },
        new Property() {
            Key = "LASTNAME", Value = txtLastname.Text
        },
        new Property() {
            Key = "EMAIL", Value = txtEmail.Text
        }
    };
    
    //4. Call webservice method
    int resultcode = indu.TriggerCampaign("TEST", props, out error);
    lblMessage.Text = resultcode + " " + error;
}

When the code is complete, save it and build the solution (ctrl+shift+b) before testing it.

Calling the method with PHP

In php we have a build-in class to call a soap service called soapclient. We are going to build the exact same example as for asp.net.

<form action="triggercampaign.php" method="post">
    <fieldset>
        <legend>Trigger a campaign</legend>
        <table>
            <tr>
                <td>Firstname: </td>
                <td><input id="txtFirstname" name="txtFirstname" /></td>
            </tr>
            <tr>
                <td>Lastname: </td>
                <td><input id="txtLastname" name="txtLastname" /></td>
            </tr>
            <tr>
                <td>Email: </td>
                <td><input id="txtEmail" name="txtEmail" /></td>
            </tr>
        </table>
        <br />
        <input type="submit" id="btnTriggerCampaign" name="btnTriggerCampaign" value="Trigger campaign" />
        <br />
        <?php print_r($outputtriggercampaign); ?>
    </fieldset>
</form>

The PHP code:

1. Set login and password

   Copy

   $login = 'XXXXX';
   $password = 'XXXXX';

2. Create instance of the soapClient

   Copy

   $client = new soapclient("http:/domain_name/automation/individual.asmx?WSDL"); 

3. Set AutomationAuthHeader from web service

   Copy

   $header = new SoapHeader(
       'http://tempuri.org/',
       'AutomationAuthHeader',
       array(
           'Login' => $login,
           'Password' => $password,
       )
   );
   $client->__setSoapHeaders($header);

4. If form for TriggerCampaign is submitted

   Copy

   if ($_POST) {

5. Validation: check input

   Copy

   $mail = "";
   $name = "";
   $firstname = "";
   $mail = $_POST['txtEmail'];
   $name = $_POST['txtLastname'];
   $firstname = $_POST['txtFirstname'];
   
   if ($mail=="" || $name=="" || $firstname=="") {
       $outputtriggercampaign = 'fill in every textfield';
   } else {

6. Set variables to be used as parameters in webservice call, the keys are the parameters from the input component in the journey map
   

   Copy

   $gatename = 'TEST';
   $inputdata = array();
   
   $inputdata[0] = array('Key' => 'EMAIL', 'Value' => $mail);
   $inputdata[1] = array('Key' => 'LASTNAME', 'Value' => $name);
   $inputdata[2] = array('Key' => 'FIRSTNAME', 'Value' => $firstname);
   
   $input = array('GateName' => $gatename, 'InputData' => $inputdata);

7. Call the webservice -> int TriggerCampaign(string GateName, Property[] InputData, out string ErrorStr)

   Copy

   $result = $client->TriggerCampaign($input, &$id, &$error);

8. Output: do something with the result, here we put it in a variable to print in the browser

   Copy

   $outputtriggercampaign = $result;

// set login and password
$login = 'XXXXX';
$password = 'XXXXX';

// create instance of the soapClient
$client = new soapclient("http://domain°name/automation/individual.asmx?WSDL");

// set AutomationAuthHeader from webservice
$header = new SoapHeader(
    'http://tempuri.org/',
    'AutomationAuthHeader',
    array('Login' => $login, 'Password' => $password)
);
$client->__setSoapHeaders($header);

// if form for TriggerCampaign is submitted
if($_POST){
    // Validation: check input
    $mail = "";
    $name = "";
    $firstname = "";
    $mail = $_POST['txtEmail'];
    $name = $_POST['txtLastname'];
    $firstname = $_POST['txtFirstname'];
    if ($mail=="" || $name=="" || $firstname=="") {
        $outputtriggercampaign = 'fill in every textfield';
    } else {
        // set variables to be used as parameters in webservice call
        $gatename = 'TEST';
        $inputdata = array();
        
        $inputdata[0] = array('Key' => 'EMAIL', 'Value' => $mail);
        $inputdata[1] = array('Key' => 'LASTNAME', 'Value' => $name);
        $inputdata[2] = array('Key' => 'FIRSTNAME', 'Value' => $firstname);
        
        $input = array('GateName' => $gatename, 'InputData' => $inputdata);
        
        //call the webservice -> int TriggerCampaign(string GateName, Property[] InputData, out string ErrorStr)
        $result = $client->TriggerCampaign($input, &$id, &$error);
            
        // OUTPUT: do something with the result, here we put it in a variable to print in the browser
        $outputtriggercampaign = $result;
    }
}