API

The Mobile2b API is a set of RESTful web services. Feel free to use the examples from our Postman collection. Postman is a free HTTP tool that is available for many operating systems and great for working with APIs.

Base URL

All requests are made to a uniform base URL. The base URL is dependent on the cloud environment in which your Mobile2b platform runs. If you are running on a Private or Dedicated Cloud, you will have received a custom base URL with your handover documentation.

For users of the Mobile2b Shared Cloud, the base URL is https://api.mobile2b.cloud.

In the following documentation, all API calls will be noted relative to this base URL. So in case of the Shared Cloud, /workflows would refer to the complete URL https://api.mobile2b.cloud/workflows.

All requests must be encrypted using HTTPS.

Authentication

Most requests must include an appropriate Authorization header.

There are three kinds of authorization methods:

Authentication token
Refresh token
API key (you can create an API key by going to "Integration Hub" > "API Keys")

To request an authentication token, you have to call POST /authenticate. The body of the authentication request should contain a domain/login/password combination:

{
    "domain": "your-domain",
    "login": "username-or-email",
    "password": "super-secure-123"
}

Authentication tokens are designed to be short-lived and have an expiry time of 15 minutes. It is the client's responsibility to check whether or not an authentication token has expired. If so, the client can use the provided refresh token to request a new authentication token in the background without the user having to enter her login/password combination again.

{
    "refreshToken": "{REFRESH_TOKEN}"
}

Authentication tokens are based on the JSON Web Token (JWT) format.

In subsequent ressource calls, the value of the Authorization header must include the JWT authentication token in the Bearer schema:

Authorization: Bearer {JWT}

If you want to use an API key for authorization, the Authorization header should look like this:

Authorization: ApiKey {API_KEY}

Operations

Following a RESTful design approach, the Mobile2b API uses different HTTP methods and ressource paths to perform basic CRUD operations.

Path	HTTP method	Content type	Operation	Parameters
/ressources	POST	`application/json`	Create a new object in this ressource collection
/ressources	GET		Get all objects from this ressource collection	`paged` (default: `true`) specifies whether the results should be paged or a full list. `sort` (default: `id,ASC`) specifies the sort property and direction of the response. Nested properties can also be used for sorting like so: `sort=user.lastName,DESC`. `size` (default: `10`) specifies the size of the response (only applies to paged responses). `search` specifies a search string. Setting this parameter will typically search accross all ressource properties (full-text search). Responses can be filtered by adding a specific ressource property and its desired value as a request parameter. For example `/users?firstName=John` will return all users who's first name is John. If the ressource property is a string property a contains algorithm is applied.
/ressources/{id}	GET		Get a specific object from this ressource collection
/ressources/{id}	PUT	`application/json`	Replace an entire object with a new object (id stays the same)
/ressources/{id}	PATCH	`application/merge-patch+json`	Update properties of a specific object
/ressources	DELETE		Delete all objects from this ressource collection
/ressources/{id}	DELETE		Delete a specific object from this ressource collection

Ressources

Business models

/models
To create a business model post a JSON payload like this

{
    "nameSingular": "Anlage",
    "namePlural": "Anlagen",
    "properties": [
        {
            "uuid": "a575658a-4ac3-4090-40be-853be5652f06",
            "type": "TEXT",
            "label": "Name",
            "filterable": false,
            "display": true,
            "overview": true,
            "required": true,
            "objectEditable": true
        }
    ]
}

Business objects

/models/{modelId}/objects
To create a business object base on the model above post a JSON payload like this. Note that the object property key matched the respective model property for "Name".

{
    "properties": {
        "a575658a-4ac3-4090-40be-853be5652f06": "F-1200"
    }
}

/models/{modelId}/objects/v2 This is a new endpoint for query filtering, supporting much more intuitive and flexible approach to make complex queries. The endpoint is backward-compatible with the V1 filtering endpoint which is /models/{modelId}/objects. So if you switch between the two - you should not see any difference within the responses and the behavior at all. The difference comes when the filter query param is used within the v2 endpoint. The parameter accepts as many expressions as you want. The basic usage of the api could be structured as: {key} {operator/action} {value}.

Example: (1) title eq Test , (2) title ne Test (3) title=test, etc..

You can choose among a limited set of supported operators at this stage:

eq (Equals)
ne (Not equals)
gt (Greater than)
gte (Greater than or equal to)
lt (Less than)
lte (Less than or equal to)
range (Within the range of 2 values)
in (Value is within the sequence of values)
nin (Value is not within the provided sequence of values)
co (The field contains the provided keyword)
nc (The field does not contain the provided keyword)

The operators works with the following types of values:

eq
----------------------------------------------------
(String) eq: anything
(Integer) eq: 10
(Double) eq: 10.20
(Boolean) eq: true|True|TRUE|false|False|FALSE
(Time) eq 10:20
(Date) eq: 2023-01-20
(DateTime (Zoned)) eq: 2023-01-20T09:20:00.000Z
(DateTime (Not Zoned)) eq: 2023-01-20T09:20:00.000

ne
----------------------------------------------------
(String) ne: anything
(Integer) ne: 10
(Double) ne: 10.20
(Boolean) ne: true|True|TRUE|false|False|FALSE
(Time) ne 10:20
(Date) ne: 2023-01-20
(DateTime (Zoned)) ne: 2023-01-20T09:20:00.000Z
(DateTime (Not Zoned)) ne: 2023-01-20T09:20:00.000

gt
----------------------------------------------------
(Integer) gt: 10
(Double) gt: 10.20
(Time) gt 10:20
(Date) gt: 2023-01-20
(DateTime (Zoned)) gt: 2023-01-20T09:20:00.000Z
(DateTime (Not Zoned)) gt: 2023-01-20T09:20:00.000

gte
----------------------------------------------------
(Integer) gte: 10
(Double) gte: 10.20
(Time) gte 10:20
(Date) gte: 2023-01-20
(DateTime (Zoned)) gte: 2023-01-20T09:20:00.000Z
(DateTime (Not Zoned)) gte: 2023-01-20T09:20:00.000

lt
----------------------------------------------------
(Integer) lt: 10
(Double) lt: 10.20
(Time) lt 10:20
(Date) lt: 2023-01-20
(DateTime (Zoned)) lt: 2023-01-20T09:20:00.000Z
(DateTime (Not Zoned)) lt: 2023-01-20T09:20:00.000

lte
----------------------------------------------------
(Integer) lte: 10
(Double) lte: 10.20
(Time) lte 10:20
(Date) lte: 2023-01-20
(DateTime (Zoned)) lte: 2023-01-20T09:20:00.000Z
(DateTime (Not Zoned)) lte: 2023-01-20T09:20:00.000

co
----------------------------------------------------
(String) co: asd
(String) co: 10

nc
----------------------------------------------------
(String) nc: asd
(String) nc: 10

in
----------------------------------------------------
(Integer) in 10,20,30
(Double) in 10.20,20.30
(Boolean) in true,false
(Time) in 10:20, 20:30
(Date) in 2023-01-20, 2023-01-21, 2023-02-20
(DateTime (Zoned)) in 2023-01-20T09:20:00.000Z,2023-01-20T09:21:00.000Z,2023-01-20T09:22:00.000Z
(DateTime (Not Zoned)) in 2023-01-20T09:20:00.000,2023-01-20T09:21:00.000,2023-01-20T09:22:00.000

nin
----------------------------------------------------
(Integer) nin 10,20,30
(Double) nin 10.20,20.30
(Boolean) nin true,false
(Time) nin 10:20, 20:30
(Date) nin 2023-01-20, 2023-01-21, 2023-02-20
(DateTime (Zoned)) nin 2023-01-20T09:20:00.000Z,2023-01-20T09:21:00.000Z,2023-01-20T09:22:00.000Z
(DateTime (Not Zoned)) nin 2023-01-20T09:20:00.000,2023-01-20T09:21:00.000,2023-01-20T09:22:00.000

range
----------------------------------------------------
(Integer) range: 10,20 -> in the interval [10,..,20]
(Double) range: 10.20 -> 20.30 -> in the interval [10.20,..,20.30]
(Time) range: 10:20,12:20 -> in the interval [10:20,..,12:20]
(Date) range: 2023-01-20,2023-02-20 -> in the interval [2023-01-20,..,2023-02-20]
(DateTime (Zoned)) range: 2023-01-20T09:20:00.000Z,2023-01-20T10:20:00.000Z -> in the interval [2023-01-20T09:20:00.000Z,..,2023-01-20T10:20:00.000Z]
(DateTime (Not Zoned)) range: 2023-01-20T09:20:00.000,2023-01-20T10:20:00.000 -> in the interval [2023-01-20T09:20:00.000,..,2023-01-20T10:20:00.000]

and keyword is also supported and gives you the possibilities to construct many individual expressions at once which satisfies all of the conditions.

An example of such usage is: title eq Dummy and age gte 18 and age range 19, 40

The usage possibilities are not only limited to simple queries like the ones listed above.

The power of this API comes from the fact that you can traverse upwards as much as you'd like and make complex hierarchical queries to filter by a property from the root or any other ancestor, no matter of the level it's located at.

Here is an example of such query construct:

{parentModelId}.properties.{referenceObjectProperty}_properties.{propertyId}=20

{parentModelId} is the model id of the parent in which the {referenceObjectProperty} refers to objects at.

The most widely usage is that each model have a relation to a parent model and they are associated through the properties.{referenceObjectProperty} and the value of that property is the ObjectID of the object within the concrete model.

And that's how it looks if executed against an existing models in which you filter by a property of the parent:

639dac219de1123cfcab3e72.properties.5a6f78eb-eff4-4bfd-9a7e-c056c7cbf150_properties.4eadbbe2-6d13-43d1-b90c-129e8860fbdb eq Test

Here is how you'd filter by a title of parent:

639dac219de1123cfcab3e72.properties.5a6f78eb-eff4-4bfd-9a7e-c056c7cbf150_title eq Test

Here is how you'd filter by a the title of a grand-grand-parent:

639dac219de1123cfcab3e72.properties.5a6f78eb-eff4-4bfd-9a7e-c056c7cbf150_631091d0f0de77402016d69b.properties.63ce4115f0d53a2da57ba927_63ce4179f0d53a2da57ba92c_properties.63ca7e65e300d43aae353040_title eq Test

Disecting it leads to those segments:

639dac219de1123cfcab3e72.properties.5a6f78eb-eff4-4bfd-9a7e-c056c7cbf150 in which we traverse to the first level upwards
631091d0f0de77402016d69b.properties.63ce4115f0d53a2da57ba927 which traverses a level on top of the level we reached previously
63ce4179f0d53a2da57ba92c_properties.63ca7e65e300d43aae353040 reaches the grad-grand-parent and looking among the objects of that model which satisfies our condition.

User management

/users

/groups

/roles

Flows

/flows

/runs

/bots

/webhooks

/functions

UIs

/uis

Templates

/templates

Documents

/documents

/document-collections