Description
The standard response to all method calls are encapsulated within the <methodResponse> root element. Immediately contained within this element will be one or more <item> elements. If there were multiple method calls within the original POST, then each method response will be contained within its own item element.
The default response format is XML. A PHP serialized array can also be returned if the response_type element is set to 'php' in the original method call. The standard format of a method response is as follows:
| Field | Description | Example |
|---|---|---|
| methodName | The name of the method called in the original POST. | utilities.checkemail |
| responseCode | A 3-digit numeric code corresponding to either a successful or unsuccessful method call. If unsuccessful, the code will correspond to the specific reason for the failure. Consult the Response Code section of each API method in this online guide for an understanding of what each code means. | 201 |
| responseText | The human-readable explanation of the response code | User has been added |
| responseData | Method-specific response data | |
| responseNum | The ordinal number of the response in the case that multiple method calls were POSTed in the same API call. The number represented in this element corresponds to the order in the sequence that the method was called. The default value is '1'. | 1 |
The structure of all API method responses as follows:
<methodResponse>
<item>
<methodName>name of API method</methodName>
<responseCode>method-specific response code</responseCode>
<responseText>human-readable description of the response code</responseText>
<responseData>
... method-specific data ...
</responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>
Important Points to Consider
API methods are periodically updated with new output elements added to the XML-formatted response. The Online API Guide will always be updated to document the addition of these new elements.
Your XML parser should not require reprogramming each time a new element is added to the response (unless, of course, the new element is needed for your system's program logic). Your parser should be robust enough to accommodate the appearance of new elements within the response without it failing.
Should your parser fail to correctly parse the XML-formatted response, do not automatically assume that the method call has failed. Automatically retrying the method call could result in unintended consequence. Instead, immediately suspend your API calls and contact your Account Manager or Technical Support.