# General Information

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 and cURL. 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.

# Authentication

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 and a nice REST tutorial.

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 application/json. 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.

# 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:

Method Description
GET 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.
POST Creates and saves a new resource. After it was created you can GET, PATCH or DELETE it.
PATCH Updates an existing resource. To update, you will have to add an identifier as a parameter and the resource properties you want to update.
DELETE 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:

HTTP Code Message Description Error
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 authorization 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.

Last Updated: 7/21/2020, 8:06:44 AM