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.

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:

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:

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

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 using the web interface or SOAP API. The business unit can’t conduct any sends.
Suspended - The business unit exists and users can log into it, but the business unit can’t 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:

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:

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

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

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

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

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