Monsum API Documentation

Introduction

The Monsum API was created as an XML/JSON Web Service. All of its resources are operated by a central URL. All API requests are sent as POST requests with either an XML- or JSON-formatted Body to the Service-URL. These documents describe the communication in XML Format.

General Service-URL:

https://app.monsum.com/api/1.0/api.php

Every request is encrypted with SSL when it is transmitted.

Authentication

Login to own acccount

The Standard-Authentication occurs through the existing Monsum User (E-Mail Address) und the API-Key of the respective Monsum Account. In this way, users have simple access to their own account.

API-Accesses are stateless; that means no sessions are saved. The email address and API-Key must be submitted for every request.

The authentication is conducted using HTTP Basic Authentication:


                curl -v -X POST \ 

                –u {E-Mail-Adresse}:{API-Key} \ 

                -H 'Content-Type: application/xml' \ 

                -d '{xml body}' \ 

                https://app.monsum.com/api/1.0/api.php

Login as a user

For providers of Add-ons or Mobile Apps, it is possible to conduct authentication using the email address and password of a current user. These external tools accept separate “Add-On Access Information” (their own E-Mail Address and API-Key). However, in order to authenticate the service, the users’ access information must be submitted separately.

API-Accesses are stateless; that means no sessions are saved. The access information for the Add-On, as well as the access information of the user, must be submitted for every request.

The Authentication is conducted using HTTP Basic Authentication, as well as additional HTTP Header-Data:


                curl -v -X POST \ 

                -u {E-Mail-Adresse}:{API-Key} \ 

                -H 'X-Username: {E-Mail Adresse des Benutzers}'\ 

                -H 'X-Password: {Passwort des Benutzers}' \ 

                -H 'Content-Type: application/xml' \ 

                -d '{xml body}' \ 

                https://app.monsum.com/api/1.0/api.php

Request structure

The header always inconcludes:

HTTP-Verb
Authentication
Content-Type

Example:

                 
                curl -v -X POST \ 

                -u {E-Mail-Adresse}:{API-Key} \ 

                -H 'Content-Type: application/xml' \ 

                -d '{xml body}' \ 

                https://app.monsum.com/api/1.0/api.php

The body of a request / a response always follows the same pattern. The following compo-nents constitute the frameworks:

FBAPI: Main node, constitutes all XML-data (not necessary in JSON Format!)
SERVICE: The username that should be addressed on the Server
LIMIT: Parameter concerning the limit on the number of elements in the query of a list (Standard 10)
OFFSET: Parameter concerning the specification of the first element in the query of a list
FILTER: Parameter concerning the addressing/filtering of the respective resources
DATA: Data, that should be submitted for the designated action
REQUEST: returned, repeated input data
RESPONSE: returned resource data
ERRORS: returned errors

Example of a successful retrieval of data for a client:

Request

    <?xml version="1.0" encoding="utf-8"?>
    <FBAPI>
         <SERVICE>customer.get</SERVICE>
         <FILTER>
            <CUSTOMER_ID>5376</CUSTOMER_ID>
         </FILTER>
    </FBAPI>

Response

    <?xml version="1.0" encoding="utf-8"?>
    <FBAPI>
        <REQUEST>
            <SERVICE>customer.get</SERVICE>
            <FILTER>
               <CUSTOMER_ID>5376</CUSTOMER_ID>
            </FILTER>
        </REQUEST>
        <RESPONSE>
            <CUSTOMERS>
                <CUSTOMER>
                    ...
                </CUSTOMER>
            </CUSTOMERS>
        </RESPONSE>
    </FBAPI>

Example of a wrong declaration to create a new customer:

Request

    <?xml version="1.0" encoding="utf-8"?>
    <FBAPI>
         <SERVICE>customer.create</SERVICE>
         <DATA>
            ...
         </DATA>
    </FBAPI>

Response

    <?xml version="1.0" encoding="utf-8"?>
    <FBAPI>
        <REQUEST>
            <SERVICE>customer.create</SERVICE>
            <DATA>
               ...
            </DATA>
        </REQUEST>
        <RESPONSE>
            <ERRORS>
                <ERROR> ... </ERROR>
            </ERRORS>
        </RESPONSE>
    </FBAPI>

Further comments:

SERVICE: The username(e.g. customer, user, invoice, product)is written in lowercase letters, followed by a period and the method name (get, create, update, delete).
For the response, all information in the request (LIMIT,OFFSET,FILTER, DATA) will continue to be carried and expanded using the returns (RESPONSE, ERRORS)
When filtering for more than one id in a _.get call the stucture of the according array looks as the following: JSON - "INVOICE_ID":["id1", "id2"] // XML - id1id2

Limitations

The default number of elements retrieved with a .get action is 10. You can adjust the "LIMIT" value to suit your needs.

However, the maximum number of elements for the retrieval is 100.

Monsum API