Create an API Request

Learning Objectives

After completing this unit, you’ll be able to:

• Create a Marketing Cloud Engagement contact using the REST API.
• Validate your Marketing Cloud Engagement developer environment setup.

Hello, World!

No developer learning experience is complete without a “Hello, World!” project to put your new skills to the test! Now that you created a package in Marketing Cloud Engagement and understand where to get the authentication credentials, let’s validate your development environment setup by creating a contact through the REST API.

JSON Parameters

Before we jump in and create a contact, let’s review the parameters for this simplified example of using this route. 

To see a complete list of what this API route can do, check out the Create Contacts REST reference on Salesforce Developers.

Create the API Request

Follow these steps to create a contact in Marketing Cloud Engagement using the REST API. You need access to Marketing Cloud Engagement and the package you created in the last unit. 

In your preferred API development tool, construct a request to create a new contact. 

1. Use this sample code and substitute your REST Base URI in Host and your access token in Authorization. Remember, you can find this information under the component details of your installed package.
2. Include a value for contactKey with a valid subdomain. The value for HTML Enabled is required.
3. You can enter your own email address rather than using your own sample code.

Each call accepts only one instance of each attribute set. 

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
"contactKey": "example@salesforce.com",
"attributeSets": [{
"name": "Email Addresses",
"items": [{
"values": [{
"name": "Email Address",
"value": "example@salesforce.com"
},
{
"name": "HTML Enabled",
"value": true
}]
}]
}]
}

Now that the request is created, send the request to Marketing Cloud Engagement to create a contact.

Validate the Request

Let’s confirm that your new contact now exists in Marketing Cloud Engagement. It can take a couple hours to receive a response, so don’t panic if you don’t see it right away. There are two ways you can validate your work.

First, you receive a response similar to this in your development tool.

200 (OK)
Content-Type: application/json
{
    "operationStatus": "OK",
    "rowsAffetcted": 1,
    "contactKey": "example@salesforce.com",
    "contactId": 12345678,
    "contactTypeID": 0,
    "isNewContactKey": false,
    "requestServiceMessageID": "8b51b524-28c1-46fc-9a44-02fca5b0a08c",
    "hasErrors": false,
    "resultMessages": [],
    "serviceMessageID": "80676c59-ceb9-48aa-ad35-81e150094a17"

Second, you can navigate to Contact Builder in Marketing Cloud Engagement to confirm that your contact exists.

1. In Marketing Cloud Engagement Contact Builder, click All Contacts.
2. Search for the contact you created.
3. Click the contact to review the contact data against your API request.

Congratulations! You created your first successful Marketing Cloud Engagement API request!

Not able to validate your work? Learn how to Handle Errors in REST API on Salesforce Developers.

What’s Next?

You learned a little about the Marketing Cloud Engagement APIs, SDKs, and programmatic languages available to use as you blaze trails with Marketing Cloud Engagement. You gained some administrator basics, such as the overall Marketing Cloud Engagement account structure (tenants, MIDs, endpoints, business units) and how users and permissions determine access. You even set up your developer environment and validated it by creating a Contact in Marketing Cloud Engagement. 

So, what’s next? When you’re ready to start coding, you can dive deeper into Marketing Cloud Engagement developer resources on the Marketing Cloud Engagement Developer Center. Join our huge community of developers through that site, where you can share ideas, join developer groups, read success stories, and more. 

Resources

• Trailhead: Content Builder Block SDK
• External Link: GitHub Repository - Salesforce Marketing Cloud Engagement Platform
• Salesforce Developer: Handle Errors in REST API
• Salesforce Developer: Marketing Cloud Engagement Developer Center
• Salesforce Developer: Marketing Cloud Engagement REST API - Create Contacts