Erfassen Sie Ihre Fortschritte
Trailhead-Startseite
Trailhead-Startseite

Create an API Request

Learning Objectives

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

  • Create a Marketing Cloud contact using the REST API.
  • Validate your Marketing Cloud 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 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. 

Name
Type
Required
Description
contactKey
string
Yes
Primary address for the contact
attributeSets
array
Yes
Array of information used to create a new contact
attributeSets.name
string
Yes
Name of attribute group to which to add the contact information
attributeSets.values
array
No
Name and value pairs indicating the attribute and applicable value
Note

Note

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 using the REST API. You need access to Marketing Cloud 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.
Note

Note

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 to create a contact.

Validate the Request

Let’s confirm that your new contact now exists in Marketing Cloud. 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 to confirm that your contact exists.

  1. In Marketing Cloud 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 API request!

Note

Note

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 APIs, SDKs, and programmatic languages available to use as you blaze trails with Marketing Cloud. You gained some administrator basics, such as the overall Marketing Cloud 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. 

A developer standing at her desk by her laptop wearing a Trailblazer sweatshirt and smiling.

So, what’s next? When you’re ready to start coding, you can dive deeper into Marketing Cloud developer resources on the Marketing Cloud 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