General information / FAQ

Access Tokens:

To use the onOffice API, it is necessary to authenticate with an access token.
An access token is an alphanumeric string that is appended to API requests to authenticate the application to the system and to allow the transaction.

The token can be generated in the user settings of the API user (Extras-> Settings-> User). After a client ID has been generated for the user, a secret and the API token are generated for the user. Please note the secret immediately, as it will not be displayed later.

The token has a length of 32 characters, the secret 64 characters.

Check the lenght if you get a “not authenticated” error. This way you can rule out that you made a mistake while copying or that you swapped token and secret.

Field names:w

Many API calls have a data parameter where you can specify the field names to set or to retrieve. Almost all fields specified in the enterprise administration (Extras >> settings >> administration >> tab input fields) are valid and can be passed as elements of an array in the parameter data. The field names for the API are found in the column “field”. A list of field names for the modules address and estate can be downloaded there too.

Via API, the field names can be read out via the API call Field configuration.
A list of action types and action types can be obtained with the API call Kind of action and Type of action.

Pay attention to the upper and lower case of the field names.

Singleselect and multiselect fields:

In singleselect fields, you can select one value of several from the drop-down menu, e.g. the field “type of usage” can take the value residential, business, investment or live on time.

Multiple values can be selected for multiselect fields. Therefore multiselect arrays are to be queried in array notation, e.g. "parameters":{"HerkunftKontakt":["Suchmaschine","Newsletter"]}

The values of the single and multi-select fields are listed in onOffice enterprise under Extras-> Settings-> Administration on the “Singleselect” and “Multiselect” tabs.
For many fields, self-created values can also be entered there.

For more information on single and multi-select fields, see our online Help Center here.

Cache:

The response parameter “cacheable” in every API call indicates if the API-Call is cachable. All API calls from the type “read” or “get” are cacheable. The SDK caches all “Read” and “Get” type responses when a cache object is passed from the outside.

You can use the interface onOfficeSDKCache from the SDK to implement your own cache. One example implementation of a database cache can be found in the onOffice WordPress-Plugin.

Rights for the API user:

Often, if no data can be read, the user rights for the API user are not set properly or missing. The user rights can be set in onOffice enterprise under “Extras->Settings->User->Tab API user->Select API user->Tab rights”.

Rights set to “only own” are usually not enough for the API user. See also here.

If the right “Can only see addresses/properties published on the website” is set, properties and/or addresses must be published under “Properties >> Marketing >> Own website: Publish” for the API user to read them. However, if the right is not set, the release of properties and addresses is controlled by the normal user rights (read/write/delete).

Redirection of the API version:

If you are using a live client, it will automatically redirect to the stable API version, no matter what API version you set.
If you are using a beta client, it will automatically redirect to the latest API version, no matter what API version you set.

Data types:

JSON knows the following data types:
– Zero value is represented by the keyword null.
– Boolean value is represented by the keywords true and false. These are not strings. Like null, they are therefore not enclosed in quotation marks.
– A number is a sequence of the digits 0-9, which can be preceded by a negative sign - and interrupted by a decimal point . The number can be completed by specifying an exponent e or E followed by a + or – sign and a sequence of digits 0-9.
– A character string begins and ends with double even quotation marks (“). It can contain Unicode characters and escape sequences.
– An array starts with [ and ends with ]. It contains a comma-separated, ordered list of values of the same or different types. Empty arrays are allowed.
– An object starts with { and ends with }. It contains a comma-separated, unordered list of properties. Objects without properties (“empty objects”) are allowed.
A property consists of a key and a value, separated by a colon (key:value). The keys should be unique, because different parsers handle multiple keys differently. While ECMA-404 does not require uniqueness, RFC 7159 requires that keys should be unique within an object.
The key is a character string.
The value is one of the data types.

If you get a “HMAC invalid” error: Floating point values should be encapsulated in a string, e.g. "breitengrad":"52.65434" to avoid rare rounding errors.

Time stamp:

Time stamp in Unix time. Number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970. The current timestamp may be queried e.g. via the PHP function time().

The validity of the time stamp is +- 30 seconds.
If the error timestamp invalid occurs, please check your server time. Deviations of 1 or 2 hours in the time stamp indicate a different server time than ours. It is often due to the time zone or summer/winter time.

PHP version / curl

The recommended PHP version is 5.5 or higher.
curl is a library that lets you make HTTP requests in PHP. curl must be installed on your server.

Request method POST

POST is a request method supported by HTTP used by the World Wide Web. Our API servers must be addressed via HTTP POST request.

onOffice without SDK / PHP

If you do not use the onOffice SDK for your API requests, you must additionally specify a timestamp and an HMAC code for each request. This information are described in more detail in in the action elements Overview . When using the onOffice SDK, this information is being generated automatically and does not have to be specified.

If you use another programming language, make sure that you generate the HMAC using the same method as our SDK.
The key-value pairs of the parameters array must be sorted alphabetically by key. The sorting is based on the order in which they appear in the ASCII table. The sort is non-recursively, e.g. only the first level of the array must be sorted (ksort). Possible parameters can be taken from the actions. In other programming languages the sorting function may work differently. Please make sure to work with lowercase hexadecimal representations of the MD5 value.

Status in address and estate

The “Status” field for addresses and properties can have the following values and is accessed via API using assigned integer values:

Address: “Active / Aktiv” = 1, “Archive / Archiviert” = 0
Real estate: “Active / Aktiv” = 1, “Pending / Inaktiv” = 2, “Archive / Archiviert” = 0

User rights for the API user:

The API user can only read out the data and perform the actions to which he is authorized. Think about for what you want to use the API user and assign the rights accordingly. Write and delete rights should be granted only if necessary, and not too generously.

The user rights can be set under Extras >> Settings / Einstellungen >> User / Benutzer >> Choose API user >> Tab Rights / Rechte.

If you work with individual record rights (further actions / weitere Aktionen >> data-record authorisation / Datensatzrechte), please note that the API user is not selectable in the record rights popup.
The rights of the API user are controlled by checking the “All” box.

Maximum number of data records

Most reading API calls have a hard limit of 500 records that can be queried per request.
Most reading API calls have the parameters “listlimit” and “listoffset”.

For “listlimit” the default is 20 if you have not set this parameter. The maximum is 500.
“listoffset” specifies the offset, i.e. from which record the query should start.

Request types

In general, we distinguish between read and write API calls. Read API calls can be of the action “Read” or “Get”. In the API documentation you will find these calls in the categories “Read record” for “Read” and “Request information” for “Get”.

Writing API calls have the actions “Create”, “Modify”, “Delete” and “Do”. The calls of the type “Create” can be found under “Create record”, “Modify” under “Edit record”, “Delete” under “Delete record” and “Do” under “Perform actions”.

The actions have the following values and are specified under actionid:

onOfficeSDK::ACTION_ID_READ = 'urn:onoffice-de-ns:smart:2.5:smartml:action:read';
onOfficeSDK::ACTION_ID_CREATE = 'urn:onoffice-de-ns:smart:2.5:smartml:action:create';
onOfficeSDK::ACTION_ID_MODIFY = 'urn:onoffice-de-ns:smart:2.5:smartml:action:modify';
onOfficeSDK::ACTION_ID_GET = 'urn:onoffice-de-ns:smart:2.5:smartml:action:get';
onOfficeSDK::ACTION_ID_DO = 'urn:onoffice-de-ns:smart:2.5:smartml:action:do';
onOfficeSDK::ACTION_ID_DELETE = 'urn:onoffice-de-ns:smart:2.5:smartml:action:delete';

Query relations:

In addresses, estates and other modules you can set relations like e.g. tenant, buyer, owner, contact person, estate units etc. These relations are not queried and set via estate or address calls, but this information is queried or set via the API calls “Create, Modify, Delete and Get relations”. Many relations exist also in other modules like “task”, “calendar”, “project” or “agentslog”.