This page contains information about managing business units, users, roles, and permission sets inside an Enterprise 2.0 account using the SOAP API. You can manage several aspects of the account with the SOAP API, including the mass provisioning and administration of multiple business units and users.
You can use the SOAP API to create, retrieve, and update users in your Enterprise 2.0 account. You can also create and update business units within that account. You can use exports from other databases to create the information to be used in the calls, as long as the information in question can be expressed in the API calls.
The Account object contains a new parent account node that can pull information on the parent account with a Retrieve call. This information includes:
If you want to retrieve all sub-accounts of the parent account, include the following code in your API call:
1retrieveRequest.QueryAllAccounts=true;
2retrieveRequest.QueryAllAccountsSpecified = true; //scans all sub-Accounts of parent-AccountThe AccountUser object can be associated with default business units and associated business units. The default business unit indicates the business unit that account user logs into by default, and the associated business units are more business units that user can log in to. You can assign these business units as well as roles with a call that includes the ID or the customer key of the business units. Note that you must use either ID or customer key for these assignments; you can’t mix and match the two types.
If no roles are explicitly assigned, a role defaults to information from the system database. By default, all Boolean values equal false. You can force inheritance of roles for both permission sets and permissions, but you can't create permission sets or permissions for roles.
You can create, retrieve, and update business units in an Enterprise 2.0 account using the customer key on the Account object. You can also assign roles to business units by specifying the customer key and the collection of roles to be assigned in the call. These roles apply to all users signed in to that business unit, and any denied permissions override the permissions and permission sets of the individual role.You can assign a time zone to a business unit with an Update call after creating the business unit with a Create call. All child XML rules set on the parent account apply to child business units and match the settings in Marketing Cloud Engagement.
You can set the status of a business unit and affect the ability to log into and send from that business unit until a further status change occurs. The four possible statuses for business units (applicable to all levels of the account, including the parent business unit) include the following:
You can specify the status of a business unit while creating it via the API by entering one of the values listed above for the ObjectState property on the Account object.When activating or deactivating a business unit with a change in status, IsActive and IsActiveSpecified become required fields. Reviewthe sample .NET code below:
1private static void UpdateAccount(int mid, string acctState)
2 {
3 Console.WriteLine("updating account........." + mid.ToString());
4 PartnerAPI.Account bu = new Account();
5 bu.ID = mid;
6 bu.IDSpecified = true;
7 //if (acctState.ToLower().Equals("cancelled"))
8 //{
9 bu.IsActive = 1;
10 bu.IsActiveSpecified = true;
11 //}
12 bu.InheritAddress = false;
13 bu.InheritAddressSpecified = true;
14 bu.BusinessName = "NorthernTrailOutfitters";
15 bu.City = "Indianapolis";
16 bu.Country = "USA";
17 bu.Zip = "46204";
18 bu.State = "IN";
19 bu.Address = "123 Acacia Drive";
20 bu.ObjectState = acctState; // "Normal"; // "Locked";// "Suspended"; //"Canceled";
21 //myDE.Client = new ClientID();
22 //myDE.Client.ClientID1 = localMemberID;
23 //myDE.Client.ClientID1Specified = true;
24 //myDE.Status = "DoNotImport";
25 PartnerAPI.UpdateOptions options = new UpdateOptions();
26 //make the api call
27 string callStatus = CallUpdate(new PartnerAPI.APIObject[] { bu }, options, false);
28 Console.WriteLine("Completed Updating Account " + mid.ToString() + " Press any key to continue");
29 Console.ReadLine();
30 }You can create, retrieve, update, and delete users in an Enterprise 2.0 account using the customer key on the AccountUser object. You can also assign roles to users by specifying the customer key and the collection of roles to be assigned in the call. These roles apply to the user no matter which business unit they are logged into within the Enterprise 2.0 account, but business-unit-level denied permissions and permission sets override user permissions and permission sets.
Permissions for Enterprise 2.0 users to create, update, or delete information persist across the web interface and SOAP API. The API checks the permissions granted to an Enterprise 2.0 user and applicably restricts those actions in the API as well. For example, if an Enterprise 2.0 user can’t create a data extension by using the web interface, they can’t create a data extension via the SOAP API, either. The API checks permissions assigned to a user and acts accordingly on any calls made by that user. The API does not check permissions for retrieve calls at this time. While you can assign roles and permission sets to Enterprise 2.0 users, you can’t assign granular permissions at this time.
Roles reside at the enterprise level unless otherwise specified. Any permission set or permission denied at a business unit level applies to all users within that business unit, even if the permission is enabled for a specific user. Also, any permission sets or permissions denied to a specific user apply even if those permissions are enabled in a business unit.
You can’t create private or system roles, but you can update or modify these roles. You can assign roles to users, business units, and users within a business unit:
To assign a role, you must specify the ObjectID for the role in the call.
To assign roles to a user, create a call using the AccountUser object and include the AccountUserID and the collection of roles to assign.
To assign roles to a business unit, create a call using the Account object and include the CustomerKey and the collection of roles to assign.
To assign roles to users within a business unit, create a call using the Account object and include all applicable AccountUsers with the applicable IDs and collections of roles.
You can’t delete a role from a user via the API. Save actions override default behavior. Otherwise, permissions sets and permissions are additive and don't overwrite previous assignments. You can use one call to update permission sets and roles and another call to handle the deletions to make sure all permission sets and permissions are set correctly.
Triggered sends to data extensions in an Enterprise 2.0 account updates subscriber status information for only the business unit that generated the triggered send. Any change of status to held, bounced, or unsubscribe applies to that subscriber in that business unit only and does not affect sends from other business units.
Marketing Cloud Engagement displays the status of the subscriber on the all subscriber list based on the status of that subscriber in the Enterprise 2.0 administrative account. Changes at the business unit level don't reflect in that status. Ensure that you retrieve the status of a subscriber from the specific business unit for the most accurate information.
The external key for a triggered send resides at the business unit level, and triggered sends from different business units in the same account can use the same external key. When making a call from the parent business unit, ensure that you pass the correct ClientID for that triggered send in your calls.
Use the sample code below to manage tasks in an Enterprise 2.0 account via the SOAP API.
1private static void CreateNewUserWithExistingRole(SoapClient client)
2{
3 AccountUser au = new AccountUser();
4 au.Name = "Test User 2 from API";
5 au.IsAPIUser = true;
6 au.IsAPIUserSpecified = true;
7 au.Client = new ClientID();
8 au.Client.ID = 1234567;
9 au.Client.IDSpecified = true;
10 au.UserID = "XXXXXXX";
11 au.Password = "XXXXXXX";
12 au.Email = "useremail@example.com";
13 au.DefaultBusinessUnit = 1234567;
14 au.DefaultBusinessUnitSpecified = true;
15 Role role = new Role();
16 role.CustomerKey = "Agent";
17 au.Roles = new Role[] { role };
18 string requestId, status;
19 CreateResult[] results = client.Create(new CreateOptions(), new APIObject[] { au }, out requestId, out status);
20}1public partial class API_ADD_E20_USERS : System.Web.UI.Page
2 {
3 protected void Page_Load(object sender, EventArgs e)
4 {
5
6 }
7 protected void btnAddSubs_Click(object sender, EventArgs e)
8 {
9 string Username, Password;
10
11 Username = "XXXXX";
12 Password = "XXXXX";
13 SoapClient client = new ExactTargetWebReference.SoapClient();
14 client.ClientCredentials.UserName.UserName = Username;
15 client.ClientCredentials.UserName.Password = Password;
16
17 AccountUser accountUser = new AccountUser();
18 accountUser.Name = "Angel Cruz";
19 accountUser.UserID = "acruz@example.com";
20 accountUser.IsAPIUser = true;
21 accountUser.IsAPIUserSpecified = true;
22 accountUser.IsLocked = false;
23 accountUser.IsLockedSpecified = true;
24 accountUser.Password = "XXXXX";
25 accountUser.MustChangePassword = false;
26 accountUser.MustChangePasswordSpecified = true;
27 accountUser.Email = "acruz@example.com";
28 accountUser.DefaultBusinessUnit = 1234546;
29 accountUser.DefaultBusinessUnitSpecified = true;
30 UserAccess access = new UserAccess();
31 //3 CLIENT_ADMIN Add Users to Account
32 //4 PRO_ADMIN Create/View Accounts
33 access.ID = 3;
34 access.IDSpecified = true; //.Net specific
35 accountUser.UserPermissions = new UserAccess[] {access};
36
37 //This tells that create user in subaccount
38
39 ClientID clientID = new ClientID();
40 // clientID.PartnerClientKey = account.PartnerKey;
41 clientID.ID = 12345;
42 clientID.IDSpecified = true;
43 accountUser.Client = clientID;
44
45 String requestId = null;
46 String overAllStatus = null;
47 CreateResult[] results = client.Create(new CreateOptions(), new APIObject[] { accountUser }, out requestId, out overAllStatus);
48
49 string errorStr = null;
50
51 if (results != null)
52 {
53 errorStr += "Status Message ### <br/>";
54 foreach (CreateResult result in results)
55 {
56
57 errorStr += result.StatusMessage + "<br/>";
58 }
59 lblMessage.Text = errorStr;
60 } else {
61 lblMessage.Text = "No results.";
62 }
63
64 }
65 }
66}1private void DeleteSubscriber()
2 {
3 SoapClient framework = new SoapClient();
4 framework.ClientCredentials.UserName.UserName = "ccc";
5 framework.ClientCredentials.UserName.Password = "ccc";
6 String requestID;
7 String status;
8 Subscriber sub = new Subscriber();
9 sub.EmailAddress = "help@example.com";
10 sub.SubscriberKey = "help@example.com";
11 SubscriberList sublist = new SubscriberList();
12 sublist.ID = 1734234; // This is the ListID you want the subscriber removed from
13 sublist.IDSpecified = true;
14 sublist.Action = "delete";
15 CreateOptions co = new CreateOptions();
16 SaveOption saveOption = new SaveOption();
17 saveOption.SaveAction = SaveAction.UpdateAdd;
18 saveOption.PropertyName = "*";
19 co.SaveOptions = new SaveOption[] { saveOption };
20
21 sub.Lists = new SubscriberList[] { sublist };
22 //Lines below are needed if the list is in a BU
23 sub.Client = new ClientID();
24 sub.Client.ID = 131464;
25 sub.Client.IDSpecified = true;
26
27 CreateResult[] cresults = framework.Create(co, new APIObject[] { sub }, out requestID, out status);
28 foreach (CreateResult result in cresults)
29 {
30 Console.WriteLine(result.StatusMessage);
31 }
32 Console.WriteLine(requestID + ": " + status);
33 }1<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2 <soap:Header>
3 <wsa:Action>Create</wsa:Action>
4 <wsa:MessageID>urn:uuid:168bbf3d-394e-4656-ae57-2e96b4b568ae</wsa:MessageID>
5 <wsa:ReplyTo>
6 <wsa:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:Address>
7 </wsa:ReplyTo>
8 <wsa:To>https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</wsa:To>
9 <wsse:Security soap:mustUnderstand="1">
10 <wsse:UsernameToken wsu:Id="SecurityToken-d19fb7b0-ec6d-49a8-8fd3-796819ec7306">
11 <wsse:Username>ccc</wsse:Username>
12 <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">ccc</wsse:Password>
13 </wsse:UsernameToken>
14 </wsse:Security>
15 </soap:Header>
16 <soap:Body>
17 <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
18 <Options>
19 <SaveOptions>
20 <SaveOption>
21 <PropertyName>*</PropertyName>
22 <SaveAction>UpdateAdd</SaveAction>
23 </SaveOption>
24 </SaveOptions>
25 </Options>
26 <Objects xsi:type="Subscriber">
27 <!--ClientID Node needed if List is in a BU-->
28 <Client>
29 <ID>121212</ID>
30 </Client>
31 <PartnerKey xsi:nil="true"/>
32 <ObjectID xsi:nil="true"/>
33 <EmailAddress>help@example.com</EmailAddress>
34 <EmailAddress>help@example.com</EmailAddress>
35 <Lists>
36 <PartnerKey xsi:nil="true"/>
37 <ID>12345</ID>
38 <ObjectID xsi:nil="true"/>
39 <Action>delete</Action>
40 </Lists>
41 </Objects>
42 </CreateRequest>
43 </soap:Body>
44</soap:Envelope>1<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2 <s:Header>
3 <a:Action s:mustUnderstand="1">Create</a:Action>
4 <a:MessageID>urn:uuid:5fba5384-6d75-43e2-a79f-4bd7c9e6e11d</a:MessageID>
5 <a:ReplyTo>
6 <a:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</a:Address>
7 </a:ReplyTo>
8 <a:To s:mustUnderstand="1">https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</a:To>
9 <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
10 <o:UsernameToken u:Id="uuid-295f6e0f-3dcb-4ce0-95ab-1434cb542498-1">
11 <o:Username>
12 USERNAME
13 </o:Username>
14 <o:Password>
15 PASSWORD
16 </o:Password>
17 </o:UsernameToken>
18 </o:Security>
19 </s:Header>
20 <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
21 <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
22 <Options>
23 <SaveOptions>
24 <SaveOption>
25 <PropertyName>*</PropertyName>
26 <SaveAction>UpdateAdd</SaveAction>
27 </SaveOption>
28 </SaveOptions>
29 </Options>
30 <Objects xsi:type="Subscriber">
31 <Client>
32 <ID>123</ID> <!-- This is the ID of the Business Unit where the List Exists -->
33 </Client>
34 <ObjectID xsi:nil="true">
35 </ObjectID>
36 <EmailAddress>help@example.com</EmailAddress>
37 <SubscriberKey>111111111111111</SubscriberKey>
38 <Lists>
39 <ID>123</ID>
40 <ObjectID xsi:nil="true">
41 </ObjectID>
42 <Status>Active</Status>
43 <Action>create</Action>
44 </Lists>
45 </Objects>
46 </CreateRequest>
47 </s:Body>
48</s:Envelope>1<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
2 <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
3 <Options>
4 <SaveOptions>
5 <SaveOption>
6 <PropertyName>*</PropertyName>
7 <SaveAction>UpdateAdd</SaveAction>
8 </SaveOption>
9 </SaveOptions>
10 </Options>
11 <Objects xsi:type="Subscriber">
12 <Client>
13 <ID>1234</ID>
14 </Client>
15 <PartnerKey xsi:nil="true"/>
16 <ObjectID xsi:nil="true"/>
17 <EmailAddress>acruz@exacttarget.com</EmailAddress>
18 <SubscriberKey>subscriberKey</SubscriberKey>
19 <Lists>
20 <Client>
21 <ID>12345</ID>
22 </Client>
23 <PartnerKey xsi:nil="true"/>
24 <ID>123456</ID>
25 <ObjectID xsi:nil="true"/>
26 </Lists>
27 </Objects>
28 <Objects xsi:type="Subscriber">
29 <Client>
30 <ID>1234567</ID>
31 </Client>
32 <PartnerKey xsi:nil="true"/>
33 <ObjectID xsi:nil="true"/>
34 <EmailAddress>acruz@example.com</EmailAddress>
35 <SubscriberKey>subscriberKey</SubscriberKey>
36 <Lists>
37 <Client>
38 <ID>12345678</ID>
39 </Client>
40 <PartnerKey xsi:nil="true"/>
41 <ID>123456789</ID>
42 <ObjectID xsi:nil="true"/>
43 </Lists>
44 </Objects>
45 </CreateRequest>
46 </s:Body>1<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2 <env:Header xmlns:env="http://www.w3.org/2003/05/soap-envelope">
3 <wsa:Action>CreateResponse</wsa:Action>
4 <wsa:MessageID>urn:uuid:57144933-b856-4106-be42-65d245dc49c1</wsa:MessageID>
5 <wsa:RelatesTo>urn:uuid:7e0cca04-57bd-4481-864c-6ea8039d2ea0</wsa:RelatesTo>
6 <wsa:To>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:To>
7 <wsse:Security>
8 <wsu:Timestamp wsu:Id="Timestamp-22d54cd3-55a2-4c9a-9e6e-3ca5fe256fc4">
9 <wsu:Created>2011-09-07T13:45:45Z</wsu:Created>
10 <wsu:Expires>2011-09-07T13:50:45Z</wsu:Expires>
11 </wsu:Timestamp>
12 </wsse:Security>
13 </env:Header>
14 <soap:Body>
15 <CreateResponse xmlns="http://exacttarget.com/wsdl/partnerAPI">
16 <Results>
17 <StatusCode>OK</StatusCode>
18 <StatusMessage>Created Subscriber.</StatusMessage>
19 <OrdinalID>0</OrdinalID>
20 <NewID>481746861</NewID>
21 <Object xsi:type="Subscriber">
22 <Client>
23 <ID>12345</ID>
24 </Client>
25 <PartnerKey xsi:nil="true"/>
26 <ID>123456</ID>
27 <ObjectID xsi:nil="true"/>
28 <EmailAddress>acruz@example.com</EmailAddress>
29 <SubscriberKey>subscriberKey</SubscriberKey>
30 <Lists>
31 <Client>
32 <ID>1234567</ID>
33 </Client>
34 <PartnerKey xsi:nil="true"/>
35 <ID>12345678</ID>
36 <ObjectID xsi:nil="true"/>
37 </Lists>
38 </Object>
39 </Results>
40 <Results>
41 <StatusCode>OK</StatusCode>
42 <StatusMessage>Created Subscriber.</StatusMessage>
43 <OrdinalID>1</OrdinalID>
44 <NewID>481746861</NewID>
45 <Object xsi:type="Subscriber">
46 <Client>
47 <ID>123456</ID>
48 </Client>
49 <PartnerKey xsi:nil="true"/>
50 <ID>1234567</ID>
51 <ObjectID xsi:nil="true"/>
52 <EmailAddress>acruz@example.com</EmailAddress>
53 <SubscriberKey>subscriberKey</SubscriberKey>
54 <Lists>
55 <Client>
56 <ID>2345678</ID>
57 </Client>
58 <PartnerKey xsi:nil="true"/>
59 <ID>1234567</ID>
60 <ObjectID xsi:nil="true"/>
61 </Lists>
62 </Object>
63 </Results>
64 <RequestID>be24d95a-30f2-47ed-bcc1-355e59f06dce</RequestID>
65 <OverallStatus>OK</OverallStatus>
66 </CreateResponse>
67 </soap:Body>
68</soap:Envelope>1<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2 <s:Header>
3 <a:Action s:mustUnderstand="1">Create</a:Action>
4 <a:MessageID>urn:uuid:5fba5384-6d75-43e2-a79f-4bd7c9e6e11d</a:MessageID>
5 <a:ReplyTo>
6 <a:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</a:Address>
7 </a:ReplyTo>
8 <a:To s:mustUnderstand="1">https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</a:To>
9 <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
10 <o:UsernameToken u:Id="uuid-295f6e0f-3dcb-4ce0-95ab-1434cb542498-1">
11 <o:Username>
12 USERNAME
13 </o:Username>
14 <o:Password>
15 PASSWORD
16 </o:Password>
17 </o:UsernameToken>
18 </o:Security>
19 </s:Header>
20 <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
21 <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
22 <Options>
23 <SaveOptions>
24 <SaveOption>
25 <PropertyName>*</PropertyName>
26 <SaveAction>UpdateAdd</SaveAction>
27 </SaveOption>
28 </SaveOptions>
29 </Options>
30 <Objects xsi:type="Subscriber">
31 <Client>
32 <ID>123</ID> <!-- This is the ID of the Business Unit where the List Exists -->
33 </Client>
34 <ObjectID xsi:nil="true">
35 </ObjectID>
36 <EmailAddress>help@example.com</EmailAddress>
37 <SubscriberKey>111111111111111</SubscriberKey>
38 <Lists>
39 <ID>123</ID>
40 <ObjectID xsi:nil="true">
41 </ObjectID>
42 <Status>Active</Status>
43 <Action>create</Action>
44 </Lists>
45 </Objects>
46 </CreateRequest>
47 </s:Body>
48</s:Envelope>You can specify a ListID in a filter to retrieve results by specific lists.
1public List<UnsubEvent> GetUnsubscribeTracking(string partnerUserKey, StackConfiguration stack)
2 {
3 string requestID;
4 RetrieveRequest request = new RetrieveRequest();
5 request.ObjectType = "UnsubEvent";
6 request.RetrieveAllSinceLastBatch = true;
7 request.RetrieveAllSinceLastBatchSpecified = true;
8 request.RepeatLastResult = true;
9 request.RepeatLastResultSpecified = true;
10 request.QueryAllAccounts = true;
11 request.QueryAllAccountsSpecified = true;
12 request.Properties = new string[] { "PartnerKey", "EventDate" };
13 request.ClientIDs = new ClientID[1];
14 request.ClientIDs[0] = new ClientID();
15 request.ClientIDs[0].PartnerUserKey = partnerUserKey;
16 string overallStatus = "";
17 APIObject[] results = null;
18 List<APIObject> allResults = new List<APIObject>();
19 try
20 {
21 overallStatus = wsApiSingleton.Instance.apiRetrieve(request, out requestID, out results, stack);
22 }
23 catch (Exception e)
24 {
25 throw new Exception("API Error in Retrieve UnsubEvent information", e);
26 }
27 if (results.Length <= 0)
28 {
29 throw new Exception("API Error in Retrieve UnsubEvent information no events returned");
30 }
31 if (overallStatus == "Error")
32 {
33 throw new Exception("API Error in Retrieve UnsubEvent information");
34 }
35
36 allResults.AddRange(results);
37 while (overallStatus == "MoreDataAvailable")
38 {
39 request = new RetrieveRequest();
40 request.ContinueRequest = requestID;
41 try
42 {
43 overallStatus = wsApiSingleton.Instance.apiRetrieve(request, out requestID, out results, stack);
44 }
45 catch (Exception e)
46 {
47 throw new Exception("API Error in Retrieve UnsubEvent information", e);
48 }
49 if (results.Length <= 0)
50 {
51 throw new Exception("API Error in Retrieve UnsubEvent information");
52 }
53 if (overallStatus == "Error")
54 {
55 throw new Exception("API Error in Retrieve UnsubEvent information");
56 }
57
58 allResults.AddRange(results);
59 }
60 if (overallStatus.ToLower().Contains("error"))
61 {
62 throw new Exception(String.Format("Unsubscribe tracking returned an error result: {0}", overallStatus));
63 }
64 return allResults.ConvertAll(apiObject => (UnsubEvent)apiObject);
65 }1<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2 <s:Header>
3 <a:Action s:mustUnderstand="1">Retrieve</a:Action>
4 <a:MessageID>urn:uuid:3e8eac09-5f8b-4b72-893d-48c7027c7830</a:MessageID>
5 <a:ReplyTo>
6 <a:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</a:Address>
7 </a:ReplyTo>
8 <a:To s:mustUnderstand="1">https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</a:To>
9 <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
10 <o:UsernameToken u:Id="uuid-68c1ec09-bda5-417d-9d2a-8eca95af5298-1">
11 <o:Username>
12 USERNAME
13 </o:Username>
14 <o:Password>
15 PASSWORD
16 </o:Password>
17 </o:UsernameToken>
18 </o:Security>
19 </s:Header>
20 <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
21 <RetrieveRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
22 <RetrieveRequest>
23 <ObjectType>SubscriberList</ObjectType>
24 <Properties>Subscriber.EmailAddress</Properties>
25 <Properties>Subscriber.SubscriberKey</Properties>
26 <Properties>ID</Properties>
27 <Properties>Status</Properties>
28 <Properties>List.ID</Properties>
29 <Filter xsi:type="ComplexFilterPart">
30 <LeftOperand xsi:type="SimpleFilterPart">
31 <Property>List.ID</Property>
32 <SimpleOperator>equals</SimpleOperator>
33 <Value>INSERT ID HERE</Value>
34 </LeftOperand>
35 <LogicalOperator>AND</LogicalOperator>
36 <RightOperand xsi:type="SimpleFilterPart">
37 <Property>Status</Property>
38 <SimpleOperator>equals</SimpleOperator>
39 <Value>Unsubscribed</Value>
40 </RightOperand>
41 </Filter>
42 </RetrieveRequest>
43 </RetrieveRequestMsg>
44 </s:Body>
45</s:Envelope>This sample code uses an API user at the top level to create a subscriber list at the business unit level.
1private void btnCreateListinBU_Click(object sender, EventArgs e)
2 {
3 SoapClient framework = new SoapClient();
4 framework.ClientCredentials.UserName.UserName = "MAC_API_USER_123";
5 framework.ClientCredentials.UserName.Password = "XXXX";
6 String requestID;
7 String status;
8 List list = new List();
9 list.Description = "Test BU List";
10 list.ListName = "Test BU List";
11 CreateOptions co = new CreateOptions();
12 SaveOption saveOption = new SaveOption();
13 saveOption.SaveAction = SaveAction.UpdateAdd;
14 saveOption.PropertyName = "*";
15 co.SaveOptions = new SaveOption[] { saveOption };
16 list.Client = new ClientID();
17 list.Client.ID = 123;
18 list.Client.IDSpecified = true;
19 CreateResult[] cresults = framework.Create(co, new APIObject[] { list }, out requestID, out status);
20 foreach (CreateResult result in cresults)
21 {
22 Console.WriteLine(result.StatusMessage);
23 }
24 Console.WriteLine(requestID + ": " + status);
25 }The sample code below creates a data extension from an existing data extension template.
1public void createDataExtensionFromTemplate(deFromTemplateType aDataExtension, int ClientID, StackConfiguration stack)
2 {
3 string requestID = "";
4 string status = "";
5 DataExtension dataExtension = new DataExtension();
6 dataExtension.Name = aDataExtension.Name;
7 dataExtension.Description = aDataExtension.Description;
8 dataExtension.Template = new DataExtensionTemplate();
9 dataExtension.Template.ObjectID = getDataExtensionTemplateID(aDataExtension.TemplateName, ClientID, stack);
10 ClientID cid = new ClientID();
11 cid.ID = ClientID;
12 cid.IDSpecified = true;
13 dataExtension.Client = cid;
14 CreateResult[] createResults = null;
15 try
16 {
17 createResults = wsApiSingleton.Instance.apiCreate(new CreateOptions(), new APIObject[] { dataExtension }, out requestID, out status, stack);
18 }
19 catch (Exception e)
20 {
21 throw new Exception("API Error in Create trying to Create DataExtension from Template " + dataExtension.Name, e);
22 }
23 if (createResults.Length != 1)
24 {
25 throw new Exception("API Error in Create trying to DataExtension from Template " + dataExtension.Name);
26 }
27 if (status == "Error")
28 {
29 throw new Exception("API Error in Create trying to DataExtension from Template " + dataExtension.Name + ((Result)(createResults[0])).StatusMessage);
30 }
31 }
32
33 public string getDataExtensionTemplateID(string dateExtensionTemplateName, int ClientID, StackConfiguration stack)
34 {
35 string status = "";
36 string requestID = "";
37 APIObject[] extensions;
38 RetrieveRequest deRetrieveRequest = new RetrieveRequest();
39 deRetrieveRequest.Properties = new string[] { "ObjectID", "Name", "CustomerKey" };
40 deRetrieveRequest.ObjectType = "DataExtensionTemplate";
41 deRetrieveRequest.ClientIDs = new ClientID[1];
42 deRetrieveRequest.ClientIDs[0] = new ClientID();
43 deRetrieveRequest.ClientIDs[0].IDSpecified = true;
44 deRetrieveRequest.ClientIDs[0].ID = ClientID;
45 SimpleFilterPart sfp = new SimpleFilterPart();
46 sfp.Property = "Name";
47 sfp.SimpleOperator = SimpleOperators.equals;
48 sfp.Value = new string[] { dateExtensionTemplateName };
49 deRetrieveRequest.Filter = sfp;
50 status = wsApiSingleton.Instance.apiRetrieve(deRetrieveRequest, out requestID, out extensions, stack);
51 if (extensions.Length != 1)
52 {
53 throw new Exception("couldn't fetch data extension template");
54 }
55 DataExtensionTemplate det = extensions[0] as DataExtensionTemplate;
56 return det.ObjectID;
57 }This SOAP envelope illustrates how an API user at the top level creates a data extension at the business unit level.
1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:par="http://exacttarget.com/wsdl/partnerAPI" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2 <soapenv:Header>
3 <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
4 <wsse:UsernameToken wsu:Id="UsernameToken-4" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5 <wsse:Username>XXX</wsse:Username>
6 <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXX</wsse:Password>
7 </wsse:UsernameToken>
8 </wsse:Security>
9 </soapenv:Header>
10 <soapenv:Body>
11 <par:CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
12 <par:Objects xsi:type="DataExtension">
13 <par:Client>
14 <par:ID>12345</par:ID>
15 </par:Client>
16 <par:CustomerKey>6789</par:CustomerKey>
17 <par:Name>BUDataExtension</par:Name>
18 <par:Description>DataExtensionDescription</par:Description>
19 <par:Fields>
20 <par:Field>
21 <par:Name>SMTP_ADDR</par:Name>
22 <par:IsPrimaryKey>true</par:IsPrimaryKey>
23 <par:IsRequired>true</par:IsRequired>
24 <par:FieldType>EmailAddress</par:FieldType>
25 </par:Field>
26 <par:Field>
27 <par:Name>ChannelMemberID</par:Name>
28 <par:IsRequired>true</par:IsRequired>
29 <par:FieldType>Number</par:FieldType>
30 <par:DefaultValue>1234567</par:DefaultValue>
31 </par:Field>
32 </par:Fields>
33 <par:IsSendable>true</par:IsSendable>
34 <par:SendableDataExtensionField>
35 <par:Name>SMTP_ADDR</par:Name>
36 </par:SendableDataExtensionField>
37 <par:SendableSubscriberField>
38 <par:Name>Email Address</par:Name>
39 </par:SendableSubscriberField>
40 </par:Objects>
41 </par:CreateRequest>
42 </soapenv:Body>
43</soapenv:Envelope>1Dim requestID As [String]
2Dim status As [String]
3Dim email As New Email()
4Dim ClientIds As New ClientID()
5With ClientIds
6 .ID = 1058396
7 .IDSpecified = True
8End With
9email.Client = ClientIds
10email.Name = "Test2"
11email.Subject = "My Subject "
12email.HTMLBody = "<center>##My content</center>"
13email.TextBody = "My Content"
14email.CharacterSet = "iso-8859-1"
15'email folder ID
16email.CategoryID = 282
17email.CategoryIDSpecified = True
18Dim results As CreateResult() = client.Create(New CreateOptions(), New APIObject() {email}, requestID, status)
19For Each result As CreateResult In results
20 Console.WriteLine(result.StatusCode)
21 Console.WriteLine(result.StatusMessage)
22 Console.WriteLine(result.RequestID)
23 Try
24 'Get New ID
25 Dim EmailMsgID as string = result.NewID
26 Catch ex As Exception
27 End Try
28Next
29Console.WriteLine(requestID & ": " & status)1BusinessUnit account = new BusinessUnit();
2 account.AccountType = AccountTypeEnum.BUSINESS_UNIT;
3 account.Name = Request.Form["bu_name"];
4 account.FromName = "Angela Cruz";
5 account.Email = "acruz@example.com";
6 account.InheritAddress = true;
7 account.BrandIDSpecified = false;
8 account.InheritAddressSpecified = true;
9 account.ParentID = 12345;
10 account.ParentIDSpecified = true;
11 account.Client = new ClientID();
12 account.Client.ID = 123456;
13 account.Client.IDSpecified = true;
14 APIObject[] apiObjects = { account };
15 String requestId = null;
16 String overAllStatus = null;
17 //Create the BU and populate the results object with the result
18 CreateResult[] results = client.Create(new CreateOptions(), apiObjects, out requestId, out overAllStatus);
19 json_results["status"] = overAllStatus;
20 json_results["payload"] = results[0].StatusMessage + " : " + results[0].ErrorCode;1<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2 <s:Header>
3 <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
4 <o:UsernameToken u:Id="uuid-88b91f91-bac2-489b-90fb-37e7b256e20c-1">
5 <o:Username>XXXXX</o:Username>
6 <o:Password>XXXXX</o:Password>
7 </o:UsernameToken>
8 </o:Security>
9 </s:Header>
10 <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
11 <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
12 <Objects xsi:type="Account">
13 <CustomerKey>DemoAccount</CustomerKey>
14 <ObjectID xsi:nil="true"/>
15 <AccountType>BUSINESS_UNIT</AccountType>
16 <Name>DemoAccount3</Name>
17 <Email>aruiz@example.com</Email>
18 <FromName>Angel Ruiz</FromName>
19 <BusinessName>Example.com</BusinessName>
20 <Address>123456 7th St.</Address>
21 <City>Indianapolis</City>
22 <State>IN</State>
23 <Zip>46204</Zip>
24 <IsActive>1</IsActive>
25 <IsTestAccount>false</IsTestAccount>
26 <ParentAccount>
27 <ID>123456</ID>
28 </ParentAccount>
29 <Subscription xsi:nil="true"/>
30 </Objects>
31 </CreateRequest>
32 </s:Body>
33</s:Envelope>1public string checkSendStatus(string CustomerKey, string[] propertyList, int clientID, StackConfiguration stack)
2 {
3 string requestID = String.Empty;
4 string status = String.Empty;
5 DateTime now = DateTime.Now;
6 //Adjust for dst
7 if (!System.TimeZone.CurrentTimeZone.IsDaylightSavingTime(now))
8 {
9 now = now.AddHours(-1);
10 }
11 else
12 now = now.AddHours(-2);
13 const string minutes = "-15";
14 DateTime past = now.AddMinutes(Double.Parse(minutes));
15 string nowstring = now.ToString("s");
16 string paststring = past.ToString("s");
17 RetrieveRequest request = new RetrieveRequest();
18 request.ObjectType = "Send";
19 request.Properties = propertyList;
20 SimpleFilterPart simpleFilter1 = new SimpleFilterPart() { Property = "EmailSendDefinition.CustomerKey", Value = new string[] { CustomerKey }, SimpleOperator = SimpleOperators.equals };
21 SimpleFilterPart simpleFilter2 = new SimpleFilterPart() { Property = "SentDate", Value = new string[] { paststring }, SimpleOperator = SimpleOperators.greaterThanOrEqual }; //DateValue = new DateTime[] {past}
22 SimpleFilterPart simpleFilter3 = new SimpleFilterPart() { Property = "SentDate", Value = new string[] { nowstring }, SimpleOperator = SimpleOperators.lessThanOrEqual }; //DateValue = new DateTime[] {now}
23 ComplexFilterPart cfp1 = new ComplexFilterPart();
24 ComplexFilterPart cfp2 = new ComplexFilterPart();
25 cfp2.LeftOperand = simpleFilter2;
26 cfp2.RightOperand = simpleFilter3;
27 cfp2.LogicalOperator = LogicalOperators.AND;
28 cfp1.LeftOperand = simpleFilter1;
29 cfp1.RightOperand = cfp2;
30 cfp1.LogicalOperator = LogicalOperators.AND;
31 request.Filter = cfp1;
32 string overallStatus = "";
33 APIObject[] results = null;
34 if (clientID != 0)
35 {
36 request.ClientIDs = new ClientID[]{new ClientID(){ClientID1 = clientID}};
37 request.ClientIDs[0].ClientID1Specified = true;
38 request.ClientIDs[0].IDSpecified = true;
39 request.ClientIDs[0].ID = clientID;
40 }
41 try
42 {
43 overallStatus = wsApiSingleton.Instance.apiRetrieve(request, out requestID, out results, stack);
44 if (results != null && results.Length > 0)
45 {
46 status = ((Send) results[0]).Status;
47 }
48 else
49 {
50 throw new Exception("No Send data retrieved.");
51 }
52 }
53 catch (Exception e)
54 {
55 throw new Exception("API Error in Retrieve Send information", e);
56 }
57 if (results.Length <= 0)
58 {
59 throw new Exception("API Error in Retrieve Send information, no sends Retrieved.");
60 }
61 if (overallStatus == "Error")
62 {
63 throw new Exception("API Error in Retrieve Send information");
64 }
65 return status;
66 }1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="xsi">
2 <soapenv:Header>
3 <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
4 <wsse:UsernameToken wsu:Id="UsernameToken-1256312100915" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5 <wsse:Username>XXXXX</wsse:Username>
6 <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
7 </wsse:UsernameToken>
8 </wsse:Security>
9 </soapenv:Header>
10 <soapenv:Body>
11 <RetrieveRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
12 <RetrieveRequest>
13 <ObjectType>Send</ObjectType>
14 <Properties>ID</Properties>
15 <Options>
16 <Client>
17 <ID>12345</ID>
18 </Client>
19 </Options>
20 </RetrieveRequest>
21 </RetrieveRequestMsg>
22 </soapenv:Body>
23</soapenv:Envelope>1<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2 <soap:Header>
3 <wsse:Security soap:mustUnderstand="1">
4 <wsse:UsernameToken wsu:Id="SecurityToken-35c067d1-5207-43f5-8172-bd0e60bf7e82">
5 <wsse:Username>XXXXXX</wsse:Username>
6 <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXXX</wsse:Password>
7 </wsse:UsernameToken>
8 </wsse:Security>
9 </soap:Header>
10 <soap:Body>
11 <UpdateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
12 <Objects xsi:type="BusinessUnit">
13 <PartnerKey xsi:nil="true"/>
14 <ObjectID xsi:nil="true"/>
15 <ID>131551</ID>
16 <BusinessName>NewBusinessName</BusinessName>
17 <SubscriberFilter xsi:type="SimpleFilterPart">
18 <Property>Address</Property>
19 <SimpleOperator>equals</SimpleOperator>
20 <Value>123 4th St.</Value>
21 </SubscriberFilter>
22 </Objects>
23 </UpdateRequest>
24 </soap:Body>
25</soap:Envelope>
j