Send Requests

This page covers the basics of calling Responsys REST APIs.

API Request URLs

The sequence of steps required for processing the Responsys REST API requests is:

1. Client issues an HTTP POST request to authenticate via the login endpoint. Depending on the system that hosts the Responsys account, the endpoints could be one of the following:

   • Responsys Interact 2: https://login2.responsys.net

   • Responsys Interact 5: https://login5.responsys.net

   • Responsys Interact 8: https://login.rsys8.net/

   • Responsys Interact 9: https://login.rsys9.net/

   • Global Routing (REST API): https://{AccountToken}-api.responsys.ocs.oraclecloud.com

   • Global Routing (AFTM): {AccountToken}-aftm.responsys.ocs.oraclecloud.com

   Note:

   For Global Routing customers, your unique global routing endpoint details are available in the Responsys interface. In Responsys, select Account > Global settings > Account configuration and look for the endpoint in the WS End Point field.
2. Responsys returns a JSON response with a token and an API endpoint URI to be used for subsequent API requests.
3. Client issues desired HTTP POST to the API endpoint along with the token in the HTTP HEADER.

   NOTE: Design your client API code to craft the API endpoint from the URI and the specific path of the desired API. For example, if the URI returned were <ENDPOINT_URI>, then the API endpoint to get all profile lists for an account would be https://<ENDPOINT_URI>/rest/api/v1.3/lists.

4. If the API request is successfully processed, Responsys returns a specific JSON response according to the specification of the processed API. Otherwise, an error payload is returned for interpretation.
5. Depending on the success or failure of the previous API request, take the next action.
6. Repeat step 3-5 as needed.
7. If needed, refresh the token to avoid having to re-authenticate. By default, tokens last for a fixed period of time (three hours).

API Call Processing

Responsys Web Services API calls are processed synchronously. For most calls, you should receive a response shortly after Responsys finishes processing the call. However, some of the API calls trigger system actions that are performed after the system sends the positive response back to the API caller. If those actions fail for some reason, you may have received a positive response for the API call, but the failure for subsequent actions would be recorded elsewhere.

Examples:

• API calls that trigger messages requiring personalization. Responsys processes personalization asynchronously after the API call has returned a positive response. If the personalization fails, then you may receive a positive API response, even though the message was not sent to the recipient.
• Trigger custom event API calls. These calls do not actually send the email or mobile messages. The triggerCustomEvent API call merely sends a group of recipients (that is, enactments) to a Responsys Program. The Program subsequently uses its own logic to determine if those enactments will be used by campaigns within that Program. The campaigns ultimately send the email or mobile messages.

How Enactment Batching Affects Processing

Oracle Responsys Programs enable cross-channel orchestrations with Email, SMS, and Push. If you plan to use the trigger custom event API call with cross-channel marketing programs, please review this section first.

Responsys requires the Enactment Batching feature to be enabled when using trigger custom event with Mobile App campaigns in Program. Otherwise, the Mobile App campaign events in the program will not be processed. However, there are some tradeoffs to consider before enabling the feature. When an account has Enactment Batching enabled, triggering a custom event cannot be used to perform near-real-time processing for any campaign type. Responsys will batch enactments together into a single enactment group before entering the enactments into a program. This results in at least a 10-minute delay between custom event triggering and entry into a Program.

If your account has Enactment Batching enabled and you need to send near-real-time messages, such as event reactions, then we highly recommend having your account enabled for the Real-time Events feature . This feature is intended for Responsys customers who use the Mobile App channel. Part of this feature enables you to create real-time custom events. Real-time custom events are a special type of custom event that override how Responsys handles enactments when the Enactment Batching feature is enabled. When a real-time custom event is triggered, Responsys handles the enactments in near real-time instead of batching them. This ensures that your customers receive the campaign messages (including Email, SMS, Push, and In-app) without the delay imposed by enactment batching. To have this feature enabled for your account, contact your Oracle Customer Success Manager. For more information, see the Defining Custom Event Types topic in the Oracle Responsys Help Center.

Alternatively, you can send near real-time messages by using merge-trigger API calls (or, for Mobile Push, perform a merge call and then follow it by a trigger push messages call). You can then enter the recipients into a Program orchestration, using schedule filter or other methods. Please contact your Customer Success Manager (CSM) for additional assistance or information.