 | This Web Service has been deprecated. This web service has been replaced with a newer version, see Web Service Api for updated information. |
General Notes
The AMS Developer API is provided as a web service in both SOAP 1.2 and REST styles. All SOAP calls can be made directly over http by using the
same XML structures for requests and responses. The XML types are defined in both the WSDL and a separate XSD schema.
The XSD schema docs are located here: http://kinrossgroup.com/xsd/amsservice.xsd.html
The WSDL for the SOAP service is located here: http://kinross-apis.net/ws/AMSMessageService?wsdl.
All methods in the API require the use of your account API Key. This can be found on the settings page of the AMS web application after you have logged in. All methods will throw an "Invalid API Key" fault if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters.
 | Note The API is quite new and may be refined over time. It has been tested using Axis 2 based unit tests. Some basic testing has also been done using .Net. If you have any comments or requests for additions to the API please contact developers@kinrossgroup.com |
Sending and Receiving Messages
The are two main methods in the API which centre around sending and receiving AMS messages.
Sending Messages
method: sendMessages
Sending messages basically involves sending an array of ams:message XML objects. Each message can be sent to one or more message boxes or
groups. You need to include the template ID of the message to be sent which can be obtained from the "Edit Template" page of the web application. You can also use the "external name" attribute of the template which can be more convenient and easier to remember than the ID. The server will look first for a template matching the ID then the external name. If no template is found, a "Template Not Found" fault will be returned.
The next main part is a list of addressees. These can be of user or group type (more info is available in the XSD docs). The value for an address should be the username of the target message box. The main part to deal with is the message content element. This element contains the XML content of the message you are trying to send. The Message XML Format section has more
information on determining what the XML equivalent structure of a message is for a given template. Basically, you encapsulate the XML for your message inside the message content element.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
message |
ams:message array |
One or more ams:message objects. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
status |
String |
"OK" if message sent without error. |
messageId |
String Array |
A list of message IDs corresponding to the sent messages. The returned IDs can be used to check the status of a sent message. |
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
AddressNotFound |
Thrown if one of the provided addresses cannot be found for this account. |
TemplateNotFound |
Thrown if a matching template cannot be found. Search is done by ID and then external name. |
ValidationError |
Thrown if the message content XML doesn't match the expected format for the template. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
Java Example
Receiving Messages
method: getMessages
Getting messages is essentially the reverse of the sendMessages method. The response will contain a list of all new messages, if any, encoded as ams:message objects. Apart from indicating which template the messages are related to and who sent them, they will contain a message content element which will contain the message's XML representation. The Message XML Format section has more information on determining what the XML equivalent structure of a message is for a given template.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
message |
ams:message array |
One or more ams:message objects. |
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
Checking Message Status
method: checkMessageStatus
This method allows you to check on the current status of a sent message.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
messageId |
String Array |
One or more message IDs to check on. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
messageStatus |
Array of ams:messageStatus objects |
Each ams:messageStatus object contains the requested message id and its status.
|
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
InvalidMessageId |
Thrown if the one of the message IDs is invalid or cannot be found. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
Message XML Format
The structure of XML representation of a message is determined by the external label and collection external label values used when creating the
template for that message. To assist in the development of tools to parse this XML, a sample of the XML produced by a particular template is
shown on the "Tools" section of the "Edit Template" page.
Message Box Management
Creating Message Boxes
method: createMessageBox
This method allows you to create a message box. Note that the username of a box must be globally unique and not contain any whitespace. As such we recommend using the phone number of the user including the country code, eg 6421999111.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
username |
String |
Username for the new message box. |
password |
String |
Password for the new message box. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
status |
String |
"OK" if the message box was created without error. |
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
ValidationError |
Thrown if the username is already taken or contains whitespace or if the password is blank. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
Removing Message Boxes
method: removeMessageBox
This method allows you to remove a message box. The box is permanently removed as well as all undelivered messages.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
username |
String |
Username for the message box to be removed. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
status |
String |
"OK" if the message box was removed without error. |
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
InvalidBoxUsername |
Thrown if the username is not found for this account. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
Enabling Message Boxes
method: enableMessageBox
This method allows you to enable a previously disabled message box. Enabling an already enabled message box has no effect.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
username |
String |
Username for the message box to be enabled. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
status |
String |
"OK" if the message box was enabled without error. |
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
InvalidBoxUsername |
Thrown if the username is not found for this account. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
Disabling Message Boxes
method: disableMessageBox
This method allows you to disable a message box. Disabling an already disabled message box has no effect. Disabled message boxes cannot be accessed by mobile users to send or receive messages, update templates and subscriptions. Messages can still be sent to the AMS gateway for download when the message box is re-enabled.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
username |
String |
Username for the message box to be disabled. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
status |
String |
"OK" if the message box was disabled without error. |
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
InvalidBoxUsername |
Thrown if the username is not found for this account. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
Adding Templates To Message Boxes
method: addTemplatesToMessageBox
This method allows you to add templates to a message box. Any required child templates are also automatically added. Adding a template that is already assigned to the target message box has no effect.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
username |
String |
Username for the message box to which templates are to be added. |
templateId |
String Array |
One or more template IDs of the templates to be added to this message box. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
status |
String |
"OK" if the message box was updated without error. |
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
InvalidBoxUsername |
Thrown if the username is not found for this account. |
TemplateNotFound |
Thrown if a matching template cannot be found. Search is done by ID and then external name. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
Removing Templates From Message Boxes
method: removeTemplatesFromMessageBox
This method allows you to remove templates from a message box. Any associated child templates are also automatically removed. Removing a template that is not assigned to the target message box has no effect.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
username |
String |
Username for the message box to which templates are to be removed. |
templateId |
String Array |
One or more template IDs of the templates to be removed from this message box. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
status |
String |
"OK" if the message box was updated without error. |
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
InvalidBoxUsername |
Thrown if the username is not found for this account. |
TemplateNotFound |
Thrown if a matching template cannot be found. Search is done by ID and then external name. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
Changing A Message Box Password
method: changeMessageBoxPassword
This method allows you to change the password of a message box.
Request Values
Parameter |
Type |
Value |
|---|---|---|
apiKey |
String |
Your AMS Account's API Key. |
username |
String |
Username for the message box to be updated. |
password |
String |
The new password for this message box. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
status |
String |
"OK" if the password was changed without error. |
Faults
Fault Name |
Cause |
|---|---|
InvalidApiKey |
Thrown if the API Key is incorrectly formatted or if a matching account is not found. The API Key should use lower case letters. |
InvalidBoxUsername |
Thrown if the username is not found for this account. |
ValidationError |
Thrown if the password is blank. |
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
WSDL
This is the current version of the wsdl: