Skip to end of metadata
Go to start of metadata

This Web Service has been deprecated.

Icon

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

Icon

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.
The send will fail completely if one address is invalid.
Note that the address should be the group name or the username of the target message box.

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
Example in Java using a Web Service client generated using Axis 2 and ADB for XML bindings

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.

  • "Awaiting Delivery" means that the message has been received by the gateway but has not be downloaded to the mobile device.
  • "Delivered To Device" means that the user has downloaded this message and it is considered delivered and is eligible for deletion in the future.
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.

Example XML From "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:

  • No labels