REST-based AFTM WS API

There are four areas to consider when developing your REST-based code in order to use AFTM:

1. Use your account-specific URL end point for AFTM-supported calls.
2. Use only a limited subset of REST API functions supported for AFTM.
3. Use the AFTM-specific Authentication Token for AFTM requests.
4. Handling errors and exceptions.

Use your account-specific URL end point

Once the secondary failover account is provisioned, you will receive an account-specific URL endpoint from Oracle that must be used in your AFTM software code.

If your Responsys account is set up for global routing, your URL endpoint will be a unique global routing endpoint. See Global Routing for more details.

If your account is on a legacy pod, the format of this URL will be similar to the following:

https://wsX-companyABC.responsys.net/webservices/services/ResponsysWSService

where wsX refers to the pod (for example, ws2 indicates the interact2 pod), and companyABC is the account-specific identifier, such as a company name.

If you have not received your account-specific URL endpoint, please contact your Customer Success Manager (CSM).

Use only a limited subset of REST API functions supported for AFTM

The AFTM WS API supports the following AFTM-specific tasks:

• Retrieve profile list members using query attribute (HA Retrieve List Members)
• Merge members into a profile list & trigger email messages to them (HA Merge Trigger Email)
• Merge members into a profile list and trigger email messages with attachments (HA Merge Trigger Email with Attachments)
• Merge members into a profile list & trigger SMS messages to them (HA Merge Trigger SMS)
• Trigger mobile push messages (HA Trigger Push Message)
• Merge members into a profile list (HA Merge List Members)

For authentication and refreshing your authorization token, AFTM also supports the following standard REST API authentication tasks. For these, use the instructions in the REST API Guide (links provided below) but use your account-specific URL endpoint.

• Log in with username and password
• Log in with username and certificates
• Refreshing tokens

IMPORTANT: When using these endpoints, you must send the request to the account-specific URL endpoint. Using the account-specific endpoint will return an AFTM-specific authorization token, which will also be valid on the AFTM servers, should failover occur. The format of the authentication request URL will be similar to the following (use api, not haApi, in the Service URL for auth requests):

POST https://wsX-companyABC.responsys.net/rest/api/v1.3/auth/token

Use the AFTM-specific Authentication Token for AFTM requests

After your client application has authenticated successfully, it will receive the authentication response body shown below.

• When logging in with username and password, a successful response contains the values you need.
• Logging in with username and certificates involves two REST API requests, and the response containing the values you need is the second one received from the Responsys system (step 4 in the “Log in with username and certificates” procedure).

The response body for authentication contains the authToken and subsequent endPoint values:

{
  "authToken": "<auth_token>",
  "issuedAt": <timestamp_when_token_was_issued>,
  "endPoint": "<endpoint_URI_value>"
}

Your client application must use the authToken values and subsequent endPoint values in all requests:

• Use the <endpoint_URI_value> when constructing the URI for your endpoint. The format may vary, depending on the programming language used to code the request. For example, if constructing a URL for an HA Merge Trigger Email request, it looks like this (endpoint URI + Service URL):

{endpoint_URI_value}/rest/haApi/v1.3/campaigns/{campaignName}/email

• In the Request Header, substitute the response value for <auth_token> in places where we show Authorization: <auth_token>.