Get started with Swagger

To "test" a query, click the Try it out button and enter the query you want to test. Then, click Execute - and Swagger gives you its response with related response code. By this, you can immediately check if the query is correct or wrong. Read more about our available response codes under Response codes.

If the query was correct, you can then basically copy and paste it into your service.

Example:
Let's say you want to get all people information from your connected Complete Control database: So, you go to the  people endpoint in Swagger, open the GET method and executed an input query (highlighted in pink). In return (highlighted in blue), you get the list of all people with cURL command and request URL. To ensure that your query was correct, check the response code next to the response.

The Public API has response codes for all endpoints with differing response content. These are the usual response codes like for example, code 200 for "OK" or code 404 for "Not found".

You can see an example for a successful response in the illustration above.

Code	Description	Response from Complete Control
200	Ok	[Response content depends on the endpoint.]
201	Created	Response code from server for a successful POST-request. The Location header provides a path to the created resource.
204	No content	Response code from server for a successful PUT-request. The Location header provides a path to the updated resource.
400	Bad request	Response code from server when the request has invalid data of some sort. The response content will be a JSON object with the property cause which will be a string of the cause of the error.
401	Unauthenticated	Response code from server when the provided token is not authorized.
403	Forbidden	Response code from server when the requesting client’s IP is not whitelisted.
404	Not found	Response code from server when a resource is not found.
422	Non processable entity	Response code from server for a POST- or PUT-request on validation errors. The response content will be a JSON object with the property errors which will be a key-value of errors.
500	Internal server error	These types of responses means an unexpected error occurred on the server and must be fixed by Complete Control developers.

Complete Controls Public API contains the following datatypes:

Code	Description
uint	A whole number (integer) without a decimal point that is typically non-negative. Example: 12
string	A sequence of characters, such as text or words. Example: john doe
bool	A data type that can have one of two values, typically true or false.
date	A data type that represents a specific calendar date in the following format: YYYY-MM-DD. Example: 2020-01-31
datetime	A data type that represents both date and time information in the following format: YYYY-MM-DDTHH:MM:SSZ Example: 2004-02-12T15:19:21+01:00
datasource	A specific type of data connection or reference to another entity. Datasources are used for lists of values (dropdowns) in Complete Control. A datasource value can be represented by an unsigned integers (like 1, 2, 3) or by an object that has at least an 'id' (uint) and a 'title' (string). If the endpoint supports expanding properties or relationships, you can request more information.
null	A special value (0) representing the absence of a value.
inputs	A key value object for template inputs. Please see section below for information regarding templates.
Array of ...	A list of other data types

Tip:
The Swagger documentation lists inputs with key and data type properties for each input. Booleans are already listed with example values. And data source inputs are wrapped in an array. Here an example from our Swagger documentation.

Complete Control has a dynamic template system: Templates allow you to tailor information for specific purposes which is one of Complete Control's core features. As a result, you can have e.g. several templates for different types of contracts in Complete Control.

The following product areas/entities use templates:

• Company

• Department

• Person

• Asset

• Contract

• Contract partners

For these entities, GET requests will thus always contain the template.

And when you PUT and POST requests for these entities, you must always enter the related template.

Example:
You want to change the birthday of a person in Swagger. Therefore, you create a PUT request for the related personID and enter the new birthday input value including template under Request body (here you can read more about Inputs). Click Execute - and if everything is correct and the birth date is updated, you will get the response code 204 for correct updates.

Each template has a set of inputs which are basically the fields on e.g. a person or contract card. Each input consists of a "key" - which often the name/description - and an assigned data type property for the value (e.g string or bool). null implies that the property can be empty or have no value.

On Swagger, you can find all input information you need for each endpoint. Here an example for person inputs:

Lists in Complete Control are of the type datasource. So, they have at least an assigned ID and a description (title) - but sometimes they contain also more information. Take a look at the category field from the example above.

If you want to POST or PUT information, its usually sufficient to enter the ID.

However, if you want to GET information about a datasource input, the ID often doesn't give you enough information. In these case, you can also ask for more details using the expand parameter. This returns you all available properties such as the category name.
See the example under Expand below.

Here some of the most popular parameters. The documentation on Swagger lists all available parameters for each API endpoint.

Expand

This parameter is only available for the datasource type. It allows you to request all properties for a specific input.

Let's say you want to get information about a person, and specifically all information about the person's category. You could then use the []expands parameter.

The response would then give you all available information; in this case: ID, entity, and title.

Tip!
When you ask for expanded information, you get usually at least the 'id' and the 'title' (which is usually a name or a description) in return.

Limit

Allows you to limit the number of e.g. people that are returned.

Offset

The Offset query parameter is used to exclude from a response the first N items of a resource collection. You can combine the Limit and the Offset parameters to request a particular set of items.

You can also add external IDs in Complete Control to map specific person, asset, contract or contract partner data with your system and reduce the risk for duplicates.

External IDs are only accessible through the Public API. So, they are not visible for users in Complete Control.

How to add external IDs to Complete Control

You add external IDs via a simple PUT-request. Don't forget to also include related template ID as mentioned above under Templates. In the following example, we have added an external ID to a person:

Once set, external IDs can be looked up from the LOOKUP endpoints for people, asset, contract or contract partner. The following example shows how to look up the external ID we have just set above: