Vertec REST API

Vertec provides a generic REST API to Vertec as a Web Service with version 6.8.0.17.

It is called REST and can be found in the folder Settings > Extensions > Web Services:

The REST web service is delivered inactive. To activate and use it, the same conditions must be met as for all web services (user rights and API tokens are present).

Addressing Vertec via REST API web service

The call is made via <ServerURL>/api/webservice/REST.

The Vertec objects can be accessed via /objects/<classname> Objects can be queried (GET), changed (PUT), created (POST) or deleted (DELETE).

Note on specifying the class name: In earlier Vertec versions, individual objects could be queried directly without specifying the class name, only with their ID. Starting with Vertec 6.8.0.20, this is no longer possible, the class name must always be specified. The case of the class name (in German or English) does not Role at this point.

For this purpose, the query parameters can optionally be functions, bi_measures, result_members and result_ocl(see the sections Features, Bi data (measures) and Return Values).

User rights

In order to make requests to the REST API, non-administrators need the following Rights:

• Right Execute on the Class Webservicedefinition
• For Queries via sql you need the Sql query right.
• In Vertec versions up to 6.8.0.19 you also need the Member Search permission for member searches. As of Vertec 6.8.0.20, simple member searches work without this user right. The results are checked first, and the objects to which the user does not have read permissions are removed from the list.

Query Objects (GET)

Query individual objects

• Internal id: /objects/project/1665
  • From Vertec 6.8.0.20 onwards, several objects can be used with the query parameter ids in a comma-separated list: /objects/project?ids=1665,1669
• Via Entry id: /objects/User/UserAdmin
• The current logged-in user is provided by the following endpoint: /functions/currentuser
• The metadata (class and string representation) of a single object is provided by the endpoint as of Vertec 6.8.0.20. /identify/objid

Global queries

a global query of the data can be done via member search, via OCL or via SQL.

For this purpose, a query is placed directly on the class, i.e. on /objects/Project. The query starts with a ?, followed by the corresponding query parameters. Several query parameters are & attached.

A query is mandatory. It is not possible to load all objects of the class without a query.

An authorization check is then performed for the objects found. Object on which the logged-in user does not have read rights are removed from the list.

Query via member search

Member searches are always global. If an ID is given for a single object, it is ignored.

Members are attributes (incl. Custom Field Items items) and associations (incl. Custom Links). All Members can be found in the Vertec Model Browser. Only persistent members can be queried.

Using the query parameter query_member the member name is specified, with query_value the searched value. Also custom field items and custom links are simply queried via the corresponding member name.

For each member queried, the combination of query_member and query_value numbered:

• query_member0 and query_value0,
• query_member1 and query_value1, etc.

When querying an attribute, query_value the searched value entered, matching the data type of the member:

/objects/Project?query_member0=code&query_value0=com%

searches for projects whose code starts with com. When operators are supported = and <, >, <=, >= for the data types Integer, Date, Datetime and Currency.

When querying an association, query_value the internal ID of the object you are looking for:

/objects/Project?query_member0=type&query_value0=179.

Query via SQL

Using the query parameter sql a global SQL query can be made: /objects/Project?sql=bold_id IN (SELECT project FROM openservice).

Query via OCL

Using the query parameter ocl an OCL expression is discontinued: /objects/user?ocl=user->select(active).

In contrast to SQL, OCL expressions can also be applied to individual objects: /objects/user/1665?ocl=openservices.

Return values

The result contains an object or a list of objects. By default, each result object returns the internal ID (objid), the String Representation of the object (stringrepresentation), the class name (classname) and for User Entry, whether the object is valid (isvalid) and the reason (hintisvalid), if an object is invalid.

To output additional members, you can use the query parameter result_members a comma-separated list of the corresponding members is given: /objects/project/1665?result_members=code,description,regarding. The specified members are output for each result object.

As of Vertec 6.8.0.20 result_oclon the result objects. The query parameter expects a designation for the output and an OCL expression for the value: ?result_ocl:anzahlleistungen=offeneleistungen->size.

Features

About the query parameter functions Features can be called on users, projects and phases. Several features can be specified separated by commas.

With the parameters date_from and date_till start and end dates can be passed as required. These must be in ISO 8601 format regardless of the regional settings (2026-03-31) can be indicated.

The example calls up the standard hours and working time of the logged-in user in the month of January 2026:

/functions/currentuser?functions=getStdHours,getWorkingHours&date_from=2026-01-01&date_till=2026-01-31

{
    "classname": "User",
    "stringrepresentation": "Christoph Keller",
    "objid": 1588,
    "isvalid": true,
    "hintisvalid": "",
    "getStdHours": 10710,
    "getWorkingHours": 10785
}

List of features

All features that are available via functions can be called, are listed here below.

BI Data (measures)

The REST API can provide Bi measures for the objects. The parameters for this are:

• bi_measures: The internal name of the BI measure is specified here. Several BI measures can be specified separated by commas.
• bi_date_from: Start date in ISO 8601 format (2026-01-20)
• bi_date_till: End date in ISO 8601 format
• bi_currency: Optional. For values of the units Betrag or Stundensatz, a currency code can be optionally entered if the output is not to be in the key currency. See also the article Business Intelligence.
• projection_dimension: Optional. Here a (single) dimension can be specified, after which the result is grouped (e.g. "Projekt,Projektbearbeiter" ). A detailed description can be found in the article BI API.

Example

/objects/user/1588?bi_measures=FeesExt,FeesExtCharged&bi_date_from=2025-01-01&bi_date_till=2025-12-31

{
    "classname": "User",
    "stringrepresentation": "Christoph Keller",
    "objid": 1588,
    "isvalid": true,
    "hintisvalid": "",
    "FeesExt": 68681.25,
    "FeesExtCharged": 34013.75
}

Change Data (PUT)

A PUT call adjusts an existing Vertec object. The fields to be changed are passed in the JSON body. The object ID comes from the URL and the body contains the new values for the desired members.

• PUT /objects/User/UserAdmin or /objects/User/1588
• Body: JSON set with the members to be changed

Each row contains a member name as a string, followed by the value to be entered, corresponding to the data type of the field to be set. Datum types are validated and converted (e.g. date in ISO format, booleans, integers, currencies).

{
  "abbreviation": "AD",  
  "level": 5270,    
}

For each field, the API checks whether it is a valid, persistent field of the class. Custom field items are treated equally.

For Associations, the internal ID (objid) of the object to be linked.

• Single-links: the internal ID of the object
• Multi-Links: the internal ID of a single object or a list of objects
• For custom links, the Role is set as a member and the internal ID is also passed as a value:

  {"Verwaltungsrat": 47083}

On success, as with a GET query, a result containing the updated object is returned.

Create objects (POST)

a POST call creates a new Vertec object. The class of the object is defined via the URL and the values of the fields are passed in the JSON body. Unlike PUT, this is not about updating an existing object, but about creating a new one.

• POST /objects/Project creates a new project

The JSON body looks like PUT and writes the appropriate members to the newly created object. If an error occurs (e.g. invalid value or missing right), the newly created object is deleted and an error message is returned.

If successful, the response corresponds to the output of a GET call for the newly created object.

Deleting Objects (DELETE)

a DELETE call permanently deletes an existing Vertec object. The instance to be deleted is deleted via the objid or the entryID identified in the URL.

• DELETE /objects/activity/13787

The specified object is searched for and then deleted if possible.

On success, no object is returned as a JSON response, but only the HTTP status 200 OK is returned.

Writing documents

Documents (e.g. Pdf or images) can also be saved on Activities, Expense and Accounts Payable payable via the REST API.

In the JSON body of a PUT or POST call, the corresponding document field (member name) is filled with a Base64-encoded string (value). The API decodes this Base64-encoded string and saves the file internally in its own document object.

Example: Attach a document to an invoice

• PUT /objects/Invoice/9876
• JSON Body:

{
  "document": BASE64DATEN
}

Here a document is saved for the invoice with the internal ID 9876 by using the field document with the Base64-encoded content.

Special case for activity: For activities, the field is additionally documentfullname required. This field contains the file name including the file extension so that Vertec knows the name of the stored document.

• PUT /objects/Activity/12345
• JSON Body:

{
  "document": BASE64DATEN
  "documentfullname": "Besuchsbericht.pdf"
}

In this example, the activity with the objid 12345 saves a document with the file name visit report.pdf. The API internally calls the appropriate document function of the activity class and creates a DocumentData object with the passed binary data.

Logging API access

The definitions necessary for using the REST API are implemented in the Vertec python module “vtcrest”.

The web service class VertecREST has a method onrequest(self), which is called on each WebRequest. In the base implementation, this method has no feature. You can override this method in a derived class to perform a defined feature, such as logging, for each request. Then swap the class reference in the Web service (vtcrest.VertecREST) against your new class reference. The following is an example of a onrequest(self) Implementation:

a Script called Customrest (requires extended user rights):

from vtcrest import VertecREST

class REST(VertecREST):

    def onrequest(self):
        method = self.http_method
        path = "/".join(self.path_parameters)
        query = self.querystring
        self.log("Received request: {} {}?{}".format(method, path, query))

The REST web service entry:

Error codes

The REST API typically responds with the following HTTP error codes:

400 Bad Request
This status code is used for all technical and technical errors caused by incorrect entries or invalid requests. Typical causes are:

• Invalid class or field names (e.g. “Attribute 'xyz’ not found for class Project”)
• Incorrect data types (e.g. “Value 'abc’ for member 'startdate’ could not be converted to 'date’)
• Invalid object IDs (e.g. “No Vertec object was found with objid=999999”)
• Missing or incorrect mandatory parameters (e.g. “'customer’ Inf required as parameter”)
• Syntax errors in OCL/SQL expressions
• Invalid Base64 Data on Documents
• Logic errors (e.g. “Association 'customer’ must be a multi-link, but Inf a single-link”)

403 Forbidden
This status code signals missing user rights for the requested operation. Common causes are:

• Lack of read permission for objects/fields (“Read access denied while reading member 'salary’)
• Write access denied when writing value '1000' for member 'budget’
• SQL query rights missing (“getwithsql failed – no SQL query right”)
• OCL execution rights are missing
• BI data access not allowed
• Access to WrapperLinkTypes is denied

The error messages usually include:

• affected class and internal ID
• affected field/parameter
• expected data type/value
• Original error text from Vertec (e.g. from `evalocl`, `bigetdata`, `getwithsql`)

For correct requests, HTTP is always used 200 OK returned (also with DELETE).