Run my Accounts RESTful API
Before you begin building an api integration, please contact your online accountant or sales representative (firstname.lastname@example.org). They can assist you with accounting related questions and can provide you a sandbox environment for your development. This documentation is designed for software developers who want to connect their applications to the Run my Accounts system.
API as RESTful resources
Run my Accounts’ API follows the design rules of “Representational State Transfer” as described in here.
API is based on HTTP(s)
HTTP-Methods are used to represent operations on the resources:
- GET return entities
- POST adds or changes entities
- DELETE removes entities
The basic api url is:
version=latest to access the latest version of the api. If available, other versions would be named in the resource description details.
Content-Types and field/parameter formats
The Run my Accounts API understands XML and JSON. Make sure that…
- Requests must be UTF-8 encoded. Responses are UTF-8.
- Use header „Accept“ to set the content type of the GET responses: application/json or application/xml
- POST with header Content-Type application/json or application/xml
- Valid values for boolean parameters are: true or false
- Date parameters format is: yyyy-MM-dd. Relativ dates such as today, yesterday or tomorrow are supported.
- Datetime format is yyyy-MM-dd’T’HH:mm:ss.SSSZ (Ex: 2011-10-24T10:39:18.333+02:00)
- Some string fields might be limited in length. TEXT(32) is limited to 32 characters.
HTTP response codes
200: OK – All ok with response content
204: OK – With no response content (some POST resources do not reply with content)
400: Bad Request – Your request is invalid.
403: Forbidden – Access to the requested resource or action is forbidden.
404: Not Found – The requested resource could not be found.
500: Internal Server Error – We had a problem with our server. Try again later or contact Run my Accounts.
Please obtain an api-key from you responsable Run my Accounts contact. It’s the key to access the api for your client. Add the api-key as URL.-parameter api_key.
We recommend https://www.getpostman.com/ for testing.
All resources (end points) of the api are documented in the resources folder
The entities folder contains example entites in json and xml.
In the use cases folder you will find a variety of different use cases, documented with json and xml examples.
Use of bank accounts
Bank accounts are only booked by Run my Accounts. Incoming payments by the API should never be posted directly against a bank account, but only through a current account. The corresponding current account will be opened upon request by Run my Accounts. Run my Accounts posts all customer-relevant bank account transactions against the current account, so that if the account is managed correctly, the current account is netted daily at zero.
Incoming payments must be booked with the correct amounts in the debtor system, otherwise the bookkeeping will not work. Any positions incorrectly booked by the customer must be cleared. If this is done through Run my Accounts, cleanup work is chargeable if it is due to incorrect customer handling. If incoming payments are not generally booked by the customer, Run my Accounts must be informed and be able to close the open positions independently.
Run my Accounts is responsible for maintaining the bookkeeping. Due to malfunction of the APIs on the customer side resulting errors in the bookkeeping are cleared by Run my Accounts with costs.