API

You will be challenged to:

  • Describe API objects, methods, and routes.
  • Describe the OAuth authentication flow and how an access token is used in SOAP and REST headers.
  • Evaluate the significance of response handling.

Installed Package

Concepts

  • Objects - Objects are elements that you use within policy rules.
  • Methods - for HTTP... GET, POST, PUT, DELETE, PATCH
  • Tenants & Endpoints - Marketing Cloud automatically assigns a unique, system-generated subdomain (for the end point) to each of its tenants.
  • Routes - A route is the "name" you use to access endpoints, used in the URL. A route can have multiple endpoints associated with it.
    • E.g. /address/v1/validateEmail

When to Use

REST API

  • Contacts
  • Content Builder
  • Journey Builder
  • Mobile Connect
  • MobilePush
  • Campaigns
  • Triggered Sends (may also use SOAP)

Web Services SOAP API

  • Tracking
  • Subscribers and lists
  • Automations
  • Triggered Sends (may also use REST)
  • Content
  • Most other email activities

API Caveats

  • Number of Call Limits
    • Pro 2 million
    • Corporate 6 million
    • Enterprise 200 million
  • Rate Limits
    • 2,000 SOAP calls per minute
    • 2,500 REST calls per minute

Optimize

REST API

A REST request is made of four components:

  • The endpoint
    • Is made of the root endpoint + path
    • Make use of your tenant endpoint
  • The method
    • GET
    • POST
    • PUT
    • DELETE
  • The headers
    • Can be used for things as authentication or providing information about the body content
  • The data (or body)
    • Contains the information you want to be sent to the server

Response Handling

Authentication

Processing Types

  • Synchronous - the connection remains open from the moment the request is submitted to the server by the client. The client waits until the server sends back a response. With synchronous call processing, API calls go directly to Marketing Cloud to be processed at the time they are received. If Marketing Cloud is unavailable, either for scheduled or unscheduled maintenance, synchronous API calls cannot be received and are not processed.
  • Asynchronous - Asynchronous clients don’t need to wait for a response to continue working. Therefore, microservices in an app can continue to process and send data, even when one of their partner services runs into trouble. This capability provides more reliable service to the user and can be especially valuable in cases where service availability is low or overloaded with demand.
    • ResultItem - contains the results of an asynchronous API call specified with RequestID

REST Routes

  • Uses JSON request and response bodies and resource endpoings to support multi-channel use.
  • !!! Most case are synchronous
  • !!! Payload max 4MB
  • !!! Timeout 120 seconds non-tracking
  • !!! Timeout 300 seconds with tracking

API Reference

Parse JSON

SOAP API

Methods

  • CREATE - Multiple object types can be created with one call.
  • RETRIEVE
  • UPDATE - Multiple object types can be updated with one call.
  • DELETE - Multiple object types can be deleted with one call.
  • EXECUTE
  • PERFORM
  • PLATFORM
  • CONFIGURE
  • EXTRACT
  • DESCRIBE
  • GET SYSTEM STATUS
  • QUERY

Payload

  • Header
  • Request Type/Method
    • Options (optional)
    • Object/Array
    • Attributes/Properties
    • Filters (optional)

Objects

Async Requests

  • Ideal for
    • TriggeredSends
    • DataExtensionObjects
  • Should be used when you need to prioritise
    • High Availability
    • Queued calls
    • Sequential Processing
    • Delays in the Schedule

Error Handling

Triggered Send

Available via the TriggeredSend object using the Create method. * Subscriber * [TriggerSendDefinition](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/triggeredsenddefinition.html

Error Handling

Rate Limiting Errors

  • Marketing Cloud reserves the right to throttle REST and SOAP API requests from a specific customer (account level) when those API requests cause slowed system performance. (Lifting the "ban" requires a support request.) The throttling rate depends on the rate necessary to stabilize operations. If this throttling occurs, the business unit or user causing this issue receives HTTP 429 (REST) or HTTP 500 (SOAP) error messages communicating the limited rate until the requests causing the issue cease.

REST Error Codes

  • Validation
    • Data Type
    • Message format
    • Media Type
  • Authorization
    • Privileges
    • Business Rules
  • Authentication
    • Authentication
    • Internal Server Error
  • Runtime
    • Object
    • Requests

Error Codes

Hands on Activity

Potentially covers 50-60% of the exam material in this section.

Best Practices

  • 1 Concurrent Import to data extension or lists
  • Up to 50 Sender Profiles
  • Up to 1000 import and filter definitions
  • Up to 1000 Business Units per Account
  • Up to 50 profile attributes
  • Up to 1million rows in a data extension
  • Up to 1000 users per account
  • Up to 1000 Data extensions in a Account

Resources