Skip to main content

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. 

Primary address for the contact
Array of information used to create a new contact
Name of attribute group to which to add the contact information
Name and value pairs indicating the attribute and applicable value

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. 

POST /contacts/v1/contacts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
"contactKey": "",
"attributeSets": [{
"name": "Email Addresses",
"items": [{
"values": [{
"name": "Email Address",
"value": ""
"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": "",
    "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. 

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


Keep learning for
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities