Manage Enterprise 2.0 Accounts

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.

Mass Administration of Enterprise 2.0 Accounts

You can use the SOAP API to create, retrieve, and update users in your Enterprise 2.0 account. You can also create, retrieve, update, and delete 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.

Account Object

The Account object contains a new parent account node that can pull information on the parent account with a Retrieve call. This information includes:

  • The AccountID of the parent account
  • The name of the parent account
  • The CustomerKey of the parent account
  • The AccountType for the parent account
  • The ParentID for the parent account

If you want to retrieve all sub-accounts of the parent account, include the following code in your API call:

AccountUser Object

The 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 cannot mix and match the two types.

Role Object

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.

Business Units

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.

Business Unit Status

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:

  • **Normal **- Users can log into the business unit and interact with it as expected.
  • Locked - The business unit exists, but no users can log into it via Marketing Cloud or the SOAP API. The business unit cannot conduct any sends.
  • Suspended - The business unit exists and users can log into it, but the business unit cannot conduct any sends or create any jobs.
  • Canceled - Nobody can log into the business unit. No jobs or sends can be created, and the system deactivates the applicable account.

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:

Users

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.

Permission for Enterprise 2.0 users to create, update, or delete information persist from Marketing Cloud to the 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 cannot create a data extension in Marketing Cloud, they cannot 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 cannot assign granular permissions at this time.

Roles

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 cannot 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:

  • Roles assigned to users apply to all business units within an Enterprise 2.0 account unless otherwise dictated by the business unit.
  • Roles assigned to business units apply to all users logged into a business unit.
  • Roles assigned to users within a business unit apply only when that user is logged into that specific 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 cannot 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.

Subscriber Status

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 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.

Triggered Sends

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.

Sample Code

Use the sample code below to manage tasks in an Enterprise 2.0 account via the SOAP API.

Sample .NET Code - Create a New User in an Enterprise 2.0 Account with a Predefined Role

Sample .NET Code - Create a New User in an Enterprise 2.0 Account with Specified Permissions

Sample .NET Code - Remove a Subscriber to a List

Sample SOAP Envelope - Remove Subscriber from a List

Sample SOAP Envelope - Add Subscriber to List

Sample SOAP Envelope - Add a Single Subscriber to Multiple Lists Contained in Multiple Business Units

Request

Response

Sample SOAP Envelope - Add Subscriber To A Single List

Sample .NET Code - Retrieve Unsubscribed Subscribers at List Level

You can specify a ListID in a filter to retrieve results by specific lists.

Sample SOAP Envelope - Retrieve Unsubscribed Subscribers at List Level

Sample .NET Code - Create a Subscriber List at the Business Unit Level

This sample code uses an API user at the top level to create a subscriber list at the business unit level.

Sample .NET Code - Creating a Data Extension at the Business Unit Level

The sample code below creates a data extension from an existing data extension template.

Sample SOAP Envelope - Creating a Data Extension at the Business Unit Level

This SOAP envelope illustrates how an API user at the top level creates a data extension at the business unit level.

Sample .NET Code - Create an Email at the Business Unit Level

Sample .NET Code - Create a New Business Unit

Sample PHP Code - Create a New Business Unit and a New User

Sample SOAP Envelope - Creating a New Business Unit

Sample .NET Code - Retrieving the Results of a Send in a Business Unit

Sample SOAP Envelope - Retrieving the Results of a Send in a Business Unit

Sample SOAP Envelope - Updating a Business Unit with a Filter