Jason Cort

When it comes to making your first API call within Salesforce Marketing Cloud, there's a range of options and places to start. You could start with Postman and the library of API calls there, but then you have to worry about configuring an app etc. within SFMC. That's a lot of effort when there's actually a lot you can do with the SOAP API to get yourself started without going down the routes of authentication and similar.

In summary a SOAP API Invoke with AMPScript is formed of 3 key parts

• Pick an object from the dropdown on the left here (In this case we'll use DataExtension)
• Check what SOAP API Operation you can do against it here (In this case we'll use Create, so InvokeCreate)
• Create your Invoke action in AMPScript. (This is the biggest of the 3 parts, sorry)

An InvokeCreate consists of a few key parts:

• Creating the Object (DataExtension)
• Defining the object properties (What attributes of the Object you want and how you want to define them)
• Execution of the InvokeCreate

So in this example, we’re aiming to create a new Data Extension, which we will define with

Set @de = CreateObject("DataExtension")

From now on, any properties we want to set for this DataExtenstion object, we need to use the @de variable.

Examples would be for the Name, Description and IsSendable. The structure of the SetObjectProperty function has 3 arguments

SetObjectProperty(1,2,3)

1. The API Object you are setting the property for (In this case, it's @de)
2. The API Property you're looking to update (Eg: Name)
3. The Value you want to set of the API Property in argument 2 (eg: HowToSFMCExample)

SetObjectProperty(@de,"Name","HowToSFMCExample")

SetObjectProperty(@de,"Description","Data Extension Created via API - HowToSFMC Sample")

SetObjectProperty(@de,"IsSendable","False")

But - A data extension has fields, and DataExtensionField is a different object. But you can put an object within an object. So you need to configure a DataExtensionField object too. In this case, we’ll define this with

SET @deFields = CreateObject(“DataExtensionField”)

Much like the base DataExtension object, you need to set the properties for this one too. It works just the same here where you set the API Object you're setting a property for, what the property is and what the value of that property is. For this example we're going to give the field a Name, a FieldType, whether it IsRequired, IsPrimaryKey, IsNillable (It's not for any of those) and a MaxLength of 100

SetObjectProperty(@deFields,"Name","MyFirstField") SetObjectProperty(@deFields,"FieldType","text") SetObjectProperty(@deFields,"IsRequired","False") SetObjectProperty(@deFields,"IsPrimaryKey","False") SetObjectProperty(@deFields,"IsNillable","False") SetObjectProperty(@deFields,"MaxLength","100")

Then you need to add this object to the parent object as an Array Item.

AddObjectArrayItem(@de,"Fields",@deFields)

The AddObjectArrayItem has 3 arguments, these are:

AddObjectArrayItem(1,2,3)

1. The object you are adding the array item to. In this case it is @de
2. The element of the Object you are adding that array to. In this case we're adding it to "Fields"
3. The value of the array, which we defined as @deFields

Up next is to actually execute the InvokeCreate, you can do that using a SET function to capture the response from your call.

Set @CreateMyDE = InvokeCreate(@de, @Status, @Error)

The InvokeCreate function has 3 required arguments and an additional optional argument that isn't necessary here.

InvokeCreate(1, 2,3)

1. The API Object to be created. In this case, we defined the API Object as @de
2. The AMPscript variable that will store the resulting status message. In the above example, this is set to store to @Status
3. The AMPscript variable that will store the resulting error message. In the above example, this is set to store to @Error

Seeing as the InvokeCreate function does provide us with error messaging, we should display those somewhere. So in a lot of cases when setting up an API call these can be displayed on a Cloud Page or written to a Data Extension. For this example we'll just display them on the a Cloud Page using %%=V(@Status)=%% and %%=V(@Error)=%% along with %%=V(@CreateMyDE)=%% that was used for the InvokeCreate.

Now if you take all of those snippets of broken down AMPscript and put them together, you should get this:

%%[ 
Set @de = CreateObject("DataExtension")
SetObjectProperty(@de,"Name","HowToSFMCExample")
SetObjectProperty(@de,"Description","Data Extension Created via API - HowToSFMC Sample")
SetObjectProperty(@de,"IsSendable","False")
Set @deFields = CreateObject("DataExtensionField")
SetObjectProperty(@deFields,"Name","MyFirstField")
SetObjectProperty(@deFields,"FieldType","text")
SetObjectProperty(@deFields,"IsRequired","False")
SetObjectProperty(@deFields,"IsPrimaryKey","False")
SetObjectProperty(@deFields,"IsNillable","False")
SetObjectProperty(@deFields,"MaxLength","100")
AddObjectArrayItem(@de,"Fields",@deFields)
Set @CreateMyDE = InvokeCreate(@de, @Status, @Error)
]%%
%%=V(@CreateMyDE)=%%<br> %%=V(@Status)=%% <br> %%=V(@Error)=%%

Now pop this snippet into a Cloud Page and click Schedule/Publish. You should get a nice preview pane with this in it:

Then head over to your Data Extensions root folder in the Business Unit that you've executed this in and you should see this:

Finally if you click into it, you should see your one field configured the way you defined it to be, something like this:

This should get you started with some SOAP API calls via AMPscript. If you've got any questions, keep an eye out for the Salesforce Marketing Cloud Technical Marketers Monthly calls and for the SFMC Lookup(Answers) sessions. These are the places where SFMC experts, MVPs, Marketing Champions and Salesforce Engineers themselves present cool things and answer questions from the community - live!