XML API overview

The Acoustic Campaign XML API library provides an efficient mechanism to accomplish many automation and integration tasks.

See detailed information about API requests and responses, as well as use the Postman Collection Collection to test your APIs, which includes Acoustic API Endpoints.

The XML API interface defines standard XML requests and responses for the following functions:

XML API endpoints

For all of the API endpoints below, the client token, secret, and refresh token are bound to the issuing Organization only. To ensure that you are able to access the most accurate information, be sure to use the link that corresponds to your pod.

API Limits
Limitations of how the Acoustic Campaign APIs can be used.

Acoustic Campaign has a robust API that handles the automation of most actions available through the Acoustic Campaign UI, such as adding new contacts or sending email campaigns. However, we place limits on the way our customers use our APIs to ensure that we provide the highest level of service and performance to all of our customers.

Concurrent requests and active sessions
Concurrent requests and what to expect.

API users of the legacy authentication (see more in the section on “Legacy Authentication Method”) must maintain no more than 20 active login sessions per Org at any time. To optimize the use of active sessions, make sure that your application uses the Logout API to release an active session when you are finished interacting with the API. This prevents lingering sessions that are no longer in use from blocking the creation of new active sessions. Inactive sessions that are not terminated properly with the Logout API can remain active for several minutes. All users of the Acoustic Campaign XML API are strongly encouraged to use OAuth 2.0 authentication. This token-based authentication model is much more flexible by allowing for the reuse of access tokens and eliminating the need to generate a high number of unique and active sessions.

API users must maintain no more than 10 concurrent requests per Org to the API servers during a specific time frame. Maintaining more than 10 concurrent requests can be subject to blocking by the Operations team. In most cases, a single connection to the API is adequate to handle all of your processing needs. Consider one of the asynchronous/batch APIs when nearing the maximum number of connections. These APIs are much more efficient at moving large data sets rapidly in and out of Acoustic Campaign/span>. Some robust asynchronous APIs are ImportList, ExportList, and RawRecipientDataExport.

Batching actions within a single XML envelope
Requirements for batch actions.

All submissions to the Acoustic Campaign API must contain one, and only one, action per each XML Envelope. Batching multiple actions within a single request is unsupported and can result in throttling or suspension of access to the API by the Operations team.

Processing Responses
Processing envelope responses.

During processing response envelopes, programmers can use an XML parser and algorithms that handle changes in the number of elements that are returned in the envelope. This improves the reliability of scripts that process responses.

The contents of a response envelope change in length depending on when you call them (and between releases of the Acoustic Campaign). For example, the GetJobStatus API returns responses of varying length depending on the status of the job (including WAITING, RUNNING, COMPLETE, and ERROR).

Errors
Unsuccessful responses or errors also adhere to the general format specified earlier. The XML elements in their bodies vary based on the type of error. The best way to become familiar with the responses that are caused by specific error conditions is to recreate them using the XML API Test Harness. If Acoustic Campaign is not available due to a maintenance outage, the following XML is returned:

false 52 SP.Admin Requests Forming XML API requests

The interfaces to Acoustic Campaign are facilitated through XML requests over Secure HTTP. You can make the request through either the POST or GET method.

Always begin the XML body format with the element followed by the element. For example:

<…Content…> To pass parameters, list each parameter as a child element of the operation element, as shown. 211191 [email protected]> Submitting an API request Use API Endpoints to learn how to submit an API request.

To submit a Licensed API, user can refer to the Test Harness document, which is located in the XML API Test Harness file, to obtain the appropriate API endpoint.

XML is passed as the Body of a POST. To specify encoding (for example, UTF-8) of the XML you are submitting, the XML must be part of the POST body. Submitting the XML as a URL parameter does not allow encoding to be specified. The encoding is specified as part of the Content Type in the HTTPS header (for example, Content-Type: text/xml;charset=UTF-8). If you specify an encoding attribute within the XML (for example, ),Acoustic Campaign ignores it. If you submit XML through the POST Body, but do not include the charset in Content Type, the organization default is used. If you submit a POST where the body contains content, ensure that Content-Length is specified in the HTTPS header. If passing the XML as a URL parameter (xml=), you must URL encode the XML and specify that it is URL encoded (Content-Type: application/x-www-form-urlencoded).

API requests pass either the OAuth based Access Token in the request’s header or the legacy Java™ Session ID (jsessionid) as a path parameter in the URL string.

Note: Be sure to use https and append the path parameter to the URL by using a semicolon, as opposed to the question mark separator used for appending query parameters to a URL. Do NOT pass the legacy jsessionID as a form parameter rather than a path parameter.