How to Create Users via API in Marketing Cloud
Earlier this year, I found myself in a sprint planning for a healthcare client. I was tasked with creating 70 users in Marketing Cloud. Salesforce Marketing Cloud is a digital marketing platform that automates marketing across email, social media, mobile apps, SMS, websites, and more. The requirements were more complex than the usual user setup. Various roles and associated business units were required. I soon thought about how many points to assign to this story, and my mind went to a very high number. I didn’t want to say 21, but I felt like being that guy. My mental math: each user will take at least 20 clicks to create; 20 x 70 is 1,400 clicks with my mouse. Hence, we are here: How can you create users via API in Marketing Cloud? I didn’t know the answer, but did know that 1,400 clicks were not in my future. Not a chance.
The process flow for creating a user in Marketing Cloud is time consuming. You create a new user, enter their name and then enter a reply email address, and Marketing Cloud pauses with a small screen refresh — BTW, what is that? — then you enter their email address, username, and the temporary password twice. Once you click Save, you must go back to the My Users page, scroll through to locate that user, click the box next to their name, and repeat this twice for both Manage Roles and Business Units. By the end, you can scarcely trudge on — but trudge you must, because this is how Marketing Cloud works. This status quo needed to be challenged. Badly.
Perhaps you’ve been here before. Creating a few users is a chore but not the end of the world. Anything beyond that makes me recoil. I am so passionate about the technical side of the platform that I was desperate programmatically for a solution that did not involve manual data input and multiple permission selections — over and over and over again. By contrast, entering attributes in a SOAP Envelope appeals much more than slogging through the Marketing Cloud UI. Therefore, the Marketing Cloud APIs were all I could think about.
Postman
I used the Postman API platform to achieve this. If you’re familiar with Postman, great! If you’re new to it, check out this fantastic YouTube series by Salesforce MVP Shibu Abraham. Once you’ve imported the collections like Shibu says, you can continue with this solution.
To work with the API, you must first create a new Installed Package in Marketing Cloud. This yields a Client ID, Client Secret, and Authentication Base URI.
Next, enter the variables inside the Salesforce Marketing Cloud APIs collection as Shibu describes.
Back in Marketing Cloud, enter a name and description, then click Save. Finally, select Add Component, API Integration, then choose Server-to-Server, and click Next. Click all the checkboxes on the Scope under Set Server-to-Server Properties, and click Save.
(Wondering why we’re selecting all the checkboxes? Keep reading.)
Getting the ObjectID for roles
Before we jump into the API POST to create users, we need to know the ObjectIDs under the roles in the Marketing Cloud back end. Therefore, we need this value to insert into our SOAP Envelope <ObjectID> element. It’s a 36-character string, and it follows this format: xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx. In the API response, it is named roleID.
How to find the ObjectIDs? After looking through the Salesforce developer documentation with no success, searching Google, and crawling the Salesforce Stack Exchange, I found a reply from Gortonington on this post. He explains how you get these from the REST endpoint https://{{et_subdomain}}.rest.marketingcloudapis.com/platform/v1/setup/quickflow/data. A true needle in a haystack.
In Postman, this GET endpoint returns the languages, roles, and time zones associated with the token. Look for the “roleID” attribute under “roles.”
"roles": [
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Administrator",
"description": "Administrator"
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Analyst",
"description": "Analyst"
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Content Creator",
"description": "Content Creator"
},
{
"roleID": "fxXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Data Manager",
"description": "Data Manager"
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Distributed Sending User",
"description": "Distributed Sending User"
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Interaction Studio Admin",
"description": "Administer Interaction Studio"
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Interaction Studio User",
"description": "Access to Interaction Studio"
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Marketing Cloud Administrator",
"description": "Assign Marketing Cloud roles to users and manage Mobile, Social and Sites Channels, Marketing Cloud Apps and Tools."
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Marketing Cloud Channel Manager",
"description": "Create and execute cross-channel interactive marketing campaigns and administer Social and Mobile Channels"
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Marketing Cloud Content Editor/Publisher",
"description": "Create and deliver messages through Mobile and Sites Channel Apps"
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Marketing Cloud Security Administrator",
"description": "Maintain Watchdog security settings and manage user activity and alerts"
},
{
"roleID": "xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx",
"roleName": "Marketing Cloud Viewer",
"description": "View cross-channel marketing activity and results within the Marketing Cloud"
}
],Note: Unless you ticked all the boxes on the Scope under Set Server-to-Server Properties, you’ll get a 403 Forbidden error: “Insufficient privileges to complete this action.” Only after I ticked all the boxes, requested the SFMC Token, and then called the endpoint again, did I get a 200 OK return.
Copy the roles and roleIDs
I suggest you copy the roles returned and paste them elsewhere. You’re going to need these to refer to when creating your users. Why paste them elsewhere? Because I recommend you now return to the Scope under Set Server-to-Server Properties in your Installed Package, and give users Read and Write access. (Yes, remove all the checkboxes, but not for the users.) It isn’t best practice to leave the Scope open, and our next step only needs the User Scope checked.
SOAP post
Postman can make HTTP calls using SOAP, a platform-independent messaging protocol specification. Here’s how to make a SOAP request in Postman.
- Open a new request tab in Postman, and enter your SOAP endpoint URL in the address field.
- Select POST from the request method dropdown list.
- Use the endpoint https://{{et_subdomain}}.soap.marketingcloudapis.com/Service.asmx
This is the SOAP Envelope I created to Create (or Update) a User in Marketing Cloud. As the endpoint requires, your request body must include the SOAP Envelope, Header, and Body tags. In addition, the data needs to include the <elements> and any values you need to post to the service. Copy this code and enter the following XML in the text-entry area. Be sure to insert your values where indicated.
<?xml version="1.0" encoding="UTF-8"?>
<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.xs d">
<s:Header>
<a:Action s:mustUnderstand="1">Create</a:Action>
<a:To
s:mustUnderstand="1">https://{{et_subdomain}}.soap.marketingcloudapis.com/Service.asmx </a:To>
<fueloauth xmlns="http://exacttarget.com">{{dne_etAccessToken}}</fueloauth>
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
<Options>
<SaveOptions>
<SaveOption>
<PropertyName>*</PropertyName>
<SaveAction>UpdateAdd</SaveAction>
</SaveOption>
</SaveOptions>
</Options>
<Objects xsi:type="AccountUser">
<PartnerKey xsi:nil="true"></PartnerKey>
<ObjectID xsi:nil="true"></ObjectID>
<Client>
<ID>ENTER_YOUR_MID</ID>
</Client>
<UserID>ENTER_YOUR_USERNAME</UserID>
<Password>ENTER_PASSWORD</Password>
<Name>ENTER_NAME</Name>
<Email>ENTER_EMAIL</Email>
<NotificationEmailAddress>
ENTER_EMAIL_NOTIFICATION_ADDRESS
</NotificationEmail Address>
<ActiveFlag>true</ActiveFlag>
<IsAPIUser>false</IsAPIUser>
<IsLocked>false</IsLocked>
<MustChangePassword>true</MustChangePassword>
<DefaultBusinessUnit>ENTER_DEFAULT_BUSINESS_UNIT</DefaultBusinessUnit>
<Roles>
<!--Administrator-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Analyst-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Content Creator-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Data Manager-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Distributed Sending User-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Interaction Studio Admin-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Interaction Studio User-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Marketing Cloud Administrator-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Marketing Cloud Channel Manager-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Marketing Cloud Content Editor/Publisher-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<!--Marketing Cloud Security Administrator-->
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
<Role>
<ObjectID>xXxXxXxX-xXxX-XxXx-XxXx-XxXxXxXxXxXx</ObjectID>
</Role>
</Roles>
<AssociatedBusinessUnits>
<BusinessUnit>
<ID>ENTER_ASSOCIATED_BUSINESS_UNIT_1</ID>
</BusinessUnit>
<BusinessUnit>
<ID>ENTER_ASSOCIATED_BUSINESS_UNIT_2</ID>
</BusinessUnit>
</AssociatedBusinessUnits>
</Objects>
</CreateRequest>
</s:Body>
</s:Envelope>
<?xml version="1.0" encoding="utf-8"?>Now hit Send in Postman and you’ll find your new user in Marketing Cloud! It’s that easy.
Notes and findings
Your SOAP Envelope can contain multiple roles and associated business units, so add or remove them, as you see fit. If you made a mistake, update your envelope and send it back for any updates (changes).
I noticed that not all roles (roleIDs) work with this method. The Marketing Cloud Administrator SYS_DEF_IMHADMIN, Marketing Cloud Channel Manager SYS_DEF_CHANNELMANAGER, Marketing Cloud Content Editor/Publisher SYS_DEF_CONTENTEDIT, Marketing Cloud Security Administrator SYS_DEF_SECURITYADMIN, and Marketing Cloud Viewer SYS_DEF_VIEWER did not update in the UI. This must be a legacy endpoint — which is why you won’t find it in official Salesforce APIs Reference documentation. So thank you, Gortonington, for commenting on this post. I would never have gotten this far or found this solution.
I found it strange that the Distributed Sending User SYS_DEF_DS_USER, Interaction Studio Admin, and Interaction Studio User Roles did update. The newness of these roles contradicts my legacy-endpoint theory — or perhaps not. Drop a comment below with thoughts on this one!
Conclusion
In the end, I was able to successfully create users via API in Marketing Cloud. Big shout-outs to Shibu Abraham, Gortonington, and the developer community — I never would have solved this alone. Ping me on LinkedIn if this helped you — it’ll make my day.
Slalom is a global consulting firm that helps people and organizations dream bigger, move faster, and build better tomorrows for all. Learn more and reach out today.
