Info
Content

General API

The general API is designed to be able to get, list, update, create and delete data entries in the system. It can be used to automate processes like vendor management or design creation.

Models & Actions

Each data type (e.g. a cmp, a design, vendor and so on) is called a model, each model provides several actions (get/list/update/...). You can use the call to info in order to receive the OpenAPI spec of all models and actions:

https://[API-Endpoint]/info

Please note that unauthenticated calls to the info model will result in an OpenAPI spec for unauthenticated actions. In order to get all Models & Actions that are possible for your account, please authenticate first.

URL structure

Calls to models follow the structure:

https://[API-Endpoint]/model/[MODELNAME]/[ACTIONNAME]

Example:

https://[API-Endpoint]/model/CMP/list

In addition to model calls, there are calls to authentication and the OpenAPI spec:

https://[API-Endpoint]/auth/[AUTH-ACTION]
https://[API-Endpoint]/info

General message structure

Communication is done by sending JSON data back and forth. In order to start an action, please send a POST request with the following JSON data in the HTTP body:

{
  "accessType": 1,         // Access type (may be required for authentication calls)
  "lang":       1|2|3|..., // Language (optional)  
  "kmd":        "...",     // Authentication token (optional/required depending on context)  
  "key":        "..."      // Your API-Key (optional/required depending on context)
  // other fields might be required depending on context
}

The content of the JSON data may vary depending on the action to be performed. Therefore please see the Actions section here.

Depending on the project implementation a key might be required for certain actions (e.g. creating a new user). Please get in touch with your account manager in order to receive your key.

Important: Keep your key private and do not transmit it via the browser but always via server-to-server connection!

The API will respond with a JSON body that is formated as follows:

{
  "status":     "...",  // Status: Success|Error 
  "statuscode": 0..999, // Status code
  "msg":        "...",  // Human readable status message
  "model":      "...",  // Context dependend. May return model type to be displayed or null
  "action":     "...",  // Action performed
  "data":        ...    // Type and content is depended on context  
}

Error codes

The API will use the following error codes in order to signal problems. The error code is send via the statuscode property of the response.

Code Description
100-199 General error codes
101 No input data found
102 view/accessType missing or incorrect
103 No IDs submitted / IDs invalid. Please send at least one ID
104 Incorrect filter: Field X does not exist in Y
105 action is missing or incorrect
106 Parameter X is required/missing
107 Unknown or empty toolbar action
108 Action not allowed
109 Action failed
110 Action allows not more than one / or no ID.
111 Data for ID x not found.
112 Create error, see error message. Field specific messages see response.data
113 Update error, see error message. Field specific messages see response.data
114 No data for create/update an item
115 IDs need to be an array
116 Cannot sign password
117 Maximum amount of item exceeded
   
200-299 Login/access errors
201 Adserver deactivated
202 User not found
203 IP blacklisted
204 Password incorrect
205 Missing credentials
206 Unknown login error
207 IP not whitelisted
208 Passwort change necessary (password too old)
209 Access not allowed
210 Password renewal not successfull

211

Token incorrect
212 Token expired
213 Account not active yet
214 Unknown access type
215 Password change needed
216 Deactivated
217 Unknown error
218 Authentication key missing or empty
219 Two-Factor Authentication missing (send parameter 2fa)
220 Two-Factor Authentication incorrect
221 Two-Factor: OTP Code missing
222 Two-Factor: OTP Code incorrect
223 Two-Factor: Mail Code missing
224 Two-Factor: Mail Code incorrect
225 Two-Factor: SMS Code missing
226 Two-Factor: SMS Code incorrect
227 Two-Factor: Mail is sent now
228 Two-Factor: SMS is sent now
229 Password update email sent
230 Password updated
   
300-399 Internal error codes
301 Could not resolve dependency for X on Y
302 Dependency for X resulted in empty list
303 No column to update
304 Dependency error on field usage
305 Dependency error on empty field
306 List query resulted in empty field list
307 Authentication callback not found
308 API include file not found: ...
399 General internal error
   
900-999 Custom error codes, please see message

Access Types

Depending on the API structure different access types exist (JSON field "accessType"). Please get in touch with your accout manager in order to recieve the ID for the access type you can use.

Models

Depending on the project and your access rights, you may see different models (data structures to be received/inserted from/into the database). Please call action rights in order to receive a list of models and actions.

Back to top