# General Information
# Recommended Tools
We would like to give you as much help as possible in using our API, so we will provide you some (hopefully) useful examples. These examples were tested with the tools Postman (opens new window) and cURL (opens new window). We recommend Postman if you are more comfortable with a UI instead of using a terminal program.
Rest assured, you may use any tool that lets you call HTTP / REST APIs.
To prevent criminals from stealing or manipulating your data, our API is secured with API-Keys. These are unique identifiers for your currently logged in session, which stays valid for six hours.
Every call to our API needs to send this key in the header section as
api-key of the message.
See Authentication for details!
# Message Format
This API is a HTTP / REST API, so every call uses the appropriate method and will return the respective status code. For convenience, there are lists below to show you which methods and status codes we use. If you are interested in what HTTP and REST means, here is a short description about HTTP (opens new window) and a nice REST tutorial (opens new window).
Every endpoint of this API is talking JSON by default.
This means the
Content-Type header of you HTTP-Requests has to be set to
If there are exceptions it is documented for the respective API call.
If you don't know what JSON is, have a look at W3Scools (opens new window).
# HTTP Methods
The protocol HTTP has a list of so called methods defining what the endpoint should do with the message.
In this table you can see what kinds of methods we support and what they mean:
| ||Returns one resource or a list of resources. If you send an identifier to your request, you will get only one object, and a list of available objects otherwise.|
| ||Creates and saves a new resource. After it was created you can GET, PATCH or DELETE it.|
| ||Updates an existing resource. To update, you will have to add an identifier as a parameter and the resource properties you want to update.|
| ||Deletes an existing resource. After that you cannot access this resource anymore and it is no longer stored.|
Resource stands for every single object (a campaign, your account, a carrier, …) you can access with our API.
# Error Handling & Status Codes
HTTP defines return codes to tell a client the status of a call. We are using a subset of these return codes to make it easier for you to determine if your call was successful.
Here is a list of standard HTTP codes we use:
|200||OK||Your call was successful!||no|
|400||VALIDATION ERROR||You sent us an invalid message! You may have missed a field, or some fields are invalid. Have a look at the error message and the docs about the call.||yes|
|403||FORBIDDEN||Your message lacks an API-Key or the key you have sent is invalid. Have a look at Authentication for more info.||yes|
|404||NOT FOUND||This is returned if the resource you tried to get is not available. For example, you tried to access a campaign that has not been created yet.||yes|
|500||INTERNAL SERVER ERROR||If you receive this code, we have some problems. Please try again later! If you keep getting this kind of error, please contact us.||yes|
If there are more cases or codes to catch, expect them to be documented in a subsequent endpoint documentation.