When to Use Asynchronous Processing
In the Marketing Cloud Engagement REST API, some calls use synchronous processing and some use asynchronous processing. The main difference between the two processing types is how the API responds to your requests.
In a synchronous call, the API executes the operation at the time the request is made and then returns the results of the operation.
In an asynchronous call, the API accepts your request and immediately provides a request ID. However, this immediate response doesn’t mean that the system completed the operation immediately. Instead, you must issue a separate request to find the status of the operation that you’re trying to perform, and then you must issue another request to view the result of that operation.
Each type of processing has benefits and drawbacks. One type can be more suitable for your specific use case than another. Generally, synchronous processing is better for minor changes and asynchronous processing is better for extensive changes. For example, if you’re building an application that creates or updates data events one at a time, synchronous processing is likely the better option. With synchronous processing, you can provide a response quickly without issuing subsequent calls to the API to find the status. If your application updates thousands of data extension rows at once due to an event, asynchronous processing is likely the better fit.
This table includes several factors to consider when determining to use synchronous or asynchronous calls.
|Requests to create or update records result in a request ID immediately. Your request is added to the queue for processing and is executed in the order in which it was received.
|After accepting your request, the API executes it. When the operation completes, the API provides a response that includes the result of the operation.
|If the system is unavailable or undergoing maintenance, your API calls are accepted, queued, and processed at a later time.
|If the system is unavailable or undergoing maintenance, your API calls aren’t accepted because they can’t be executed.
|Volume of records
|Create and update requests are immediately accepted and added to the processing queue. This type of processing is helpful when you want to change a long list of records in a single call to the API.
|It can take several minutes to create or update a long list of records. To prevent long-running API calls, limit synchronous create and update calls to 50 rows and 50 items per request. If you have more than 50 rows to create or update, you must make several calls to the API.
|Number of calls required
|Requests to create or update records result in a request ID immediately. To view the status and the results of the request, provide this request ID in subsequent calls.
|In a single call, you can issue a request and view the result.
|If your request is well formed, the API accepts it. Because the API processes your request at a later time, the request body can contain errors that prevent the request from being executed. You only know about this failure if you issue a subsequent call to the API to view the results.
|If your request is well formed, the API accepts it and attempts to execute the request. If the request body contains errors, you receive information about the failure without issuing a subsequent call to the API.