Service information XML

Full service data is available in XML format. A link to XML file can be found under the “Setup” tab of an API service. Link example:

1
https://api.fortumo.com/api/services/2/8edae...8adcc5e.342340...ce5920a39.xml

There is a shorter version of the file available with no information regarding the operators and billing statuses. Additional parameter billing_info=false should be used in this case:

1
https://api.fortumo.com/api/services/2/8edae...8adcc5e.342340...ce5920a39.xml?billing_info=false

In order to request a single country data, an optional parameter country can be used in combination with a country code, for example country=DE for Germany:

1
https://api.fortumo.com/api/services/2/8edae...8adcc5e.342340...ce5920a39.xml?country=DE

It is recommended to schedule daily update requests of the file (for example, with a CRON job).

XML structure

  • Status – contains information about whether the XML request was successful or not.
  • Service::countries – holds all countries, associated with a service.
  • Country – holds pricing and promotional information for a specific country.
  • Price – groups short codes and operators with the same price point.
  • Message_profile – groups operators with same short code and keyword combination.
  • Operator – profile for a specific operator.
  • Operator::codes – MCC and MNC pairs for a specific operator.
  • Promotional_text – an example of promotional information for specific country.

Although in most of the countries the price point, short code and keyword are the same for all operators, there are countries where some of parameters may defer among them. In this case, there will be several price or message_profile nodes, and all_operators=false.

Note that in some of the countries customers will be asked to send a second message with a word “YES” or similar to confirm the purchase. This is called a double confirmation or double opt-in.

List of parameters

The following table gives an overview of all elements of the file and their possible values.

Parameter Value Type Description
services_api_response::version 2.0 String Version of the Fortumo XML API used. Current version is 2.0
code 0 Integer API file status code.
message OK String API file status message (see code). Default message is OK.
service::id Hash String A 32-symbol unique service id, for example 8edae35a2857e5e16fd3684ad8adcc5e
country::name France String Country name.
country::vat 19.60 Float A Float number representing current VAT or equivalent rate in the country.
country::approved true Boolean True if country is approved and live.
country::code FR String Country code in ISO 3166-1 format.
price::amount 0.35 Float Service price point.
price::vat_included true Boolean True, if the VAT rate is included in the price (price::amount).
price::all_operators true Boolean True, if the price is the same for all operators, otherwise there will be several separate blocks.
price::currency EUR String The local currency code according to ISO-4217 (list of codes).
message_profile::shortcode 63767 Integer Premium short code for sending the messages.
message_profile::keyword TXT TEST String Keywords, which will identify the message.
message_profile::all_operators true Boolean True, if the short code and keyword are the same for all operators, otherwise there will be several blocks.
message_profile:: double_confirmation_shortcode 89000 Integer Optional. The short code for additional opt-in. Only for countries with double opt-in.
message_profile:: double_confirmation_text YES String Optional. The text for additional opt-in. Only for countries with double opt-in.
operator::revenue 13.64 Float Optional. Service revenue for single transaction.
operator::name Bouygues String Optional. The full name of the mobile operator.
operator::billing_type MT String Optional. Billing type, either “MO” or “MT”
operator::default_billing_status Failed String Optional. Default billing status for transactions with no billing reports, either “OK” or “Failed”
operator::code Bouygues String Optional. The alias of the operator that will be sent to service back end as the operator parameter.
codes::mcc 282 Integer Mobile country code.
codes::mnc 11 Integer Mobile network code. Most operators have multiple pairs of corresponding MCC/MNC pairs.
promotional_text::local Prix… String An example of the pricing notice in local language.
promotional_text::english Price… String Optional. An example of the pricing notice in English.
API file statuses
  • 0 - OK (default)
  • 1 - invalid service signature
  • 2 - service not found
  • 3 - service archived
  • 4 - XML API not supported by service
  • 5 - specified country not available

Parsing the file

For automatic processing of service data XML, an XML parser should be used. It’s strongly advised to use a built-in parser provided with the development framework to avoid parsing errors. There are built-in XML parsers available for most of the programming languages. The following table gives an overview of the most popular solutions.

PHP SimpleXML, XMLReader
Javascript jQuery, XMLHttpRequest
Ruby REXML
Perl XML::Parser, XML::DOM
Java DOM XML, SAX XML, JDOM XML
Python ElementTree, Sax, MiniDom
Flash/Actionscript XMLDocument, XML
Help us improve our Merchants Portal. Was this article helpful?