Basic concepts

This section explains required basic concepts when working with the dialogportal™ REST API.

Location of API

The dialogportal™ REST API is located at: https://api.dialogportal.com/v1. Every relative URL specified throughout this document, is relative to this location.

The API is also available in our test environment at https://testapi.dialogportal.com/v1. The only important difference between the test environment and the production environment is that the AppSecret (see below) will be different for the two environments.

Apps using the dialogportal™ REST API

Any application that wants to make use of the dialogportal™ REST API must be registered in dialogportal™ and be assigned an AppKey and an AppSecret. The AppKey is just a numeric identifier and the AppSecret is a long random string. These will be used to authorize all requests to the API. More information regarding authentication can be found in the section "Authenticating requests".

In addition, all applications in dialogportal™ will be assigned a default external key type and a default data contract. See the following sections for an explanation of these concepts.

dialogportal™ master key and external keys

dialogportal™ is able to handle many different unique identifiers that may be used in external systems and applications. An external key is defined by a type (numeric value) and to use such a key, it must first be agreed upon with Fluid Solutions.

Regardless of the number of external keys, there is always the dialogportal™ master key, which is the internal unique key. This key is automatically assigned by dialogportal™ and has a fixed format and a fixed sequence.

Both types of keys can be used to communicate with the API.

Contracts

The database in dialogportal can handle a huge variety of data. It provides great flexibility in terms of the data an external system is able to deliver, what data it needs in order to operate correctly, and in general what data it has permission to make use of.

For this purpose, a contract between an application and dialogportal™ is designed. This contract describes the fields that can/should be sent/received between the application and dialogportal™ as well as the rules that apply to the individual fields, for example read and write permissions and validation.

Such a contract must be designed in cooperation with Fluid Solutions.