Ultimate

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.

Visit here for an interactive API explorer.

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 across all ressource properties (full-text search). filter allows for complex filtering of results using a dedicated filter syntax. fields specifies which fields should be included in the response. Multiple fields can be specified as comma-separated values, e.g. fields=id,name,description.
/ressources/{id}	GET		Get a specific object from this ressource collection	fields specifies which fields should be included in the response. Multiple fields can be specified as comma-separated values, e.g. fields=id,name,description.
/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:

1. eq (Equals)
2. ne (Not equals)
3. gt (Greater than)
4. gte (Greater than or equal to)
5. lt (Less than)
6. lte (Less than or equal to)
7. range (Within the range of 2 values)
8. in (Value is within the sequence of values)
9. nin (Value is not within the provided sequence of values)
10. co (The field contains the provided keyword)
11. 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

Dissecting it leads to these segments:

1. 639dac219de1123cfcab3e72.properties.5a6f78eb-eff4-4bfd-9a7e-c056c7cbf150 in which we traverse to the first level upwards
2. 631091d0f0de77402016d69b.properties.63ce4115f0d53a2da57ba927 which traverses a level on top of the level we reached previously
3. 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

📘 GET /runs — API Documentation

Retrieves flow run records using filtering and pagination.

Authentication is required using an API key.

---

🔐 Authentication Header

Authentication: ApiKey your_api_key

---

📌 Endpoint

GET /runs

Returns a paginated list of Run objects.

---

✅ Access Rules

Admin users - Can view all runs without filters.

Non-admin users - Must provide at least one filter. - Accessing /runs without filters returns a PermissionException.

---

❌ Permission Error (Non-Admin Without Filter)

A non-admin calling /runs without any filter will receive:

HTTP/1.1 400 Bad Request

PermissionException:
"You are not allowed to view all runs. Please provide a more specific filter or ask your supervisor for access."

Example request

GET /runs
Authentication: ApiKey your_api_key

---

📥 Available Filters (RunFilter)

• caseId — number
  Filter runs belonging to a specific case.

• assignedTo — string (me)
  Controls filtering based on user assignment.

• assignedUserId — number
  Filter runs assigned to a specific user.

• assignedGroupId — number
  Filter runs assigned to a group.

• flowId — string
  Returns runs belonging to a specific Flow.

• status — enum (QUEUED, IN_PROGRESS, COMPLETED, STOPPED, STUCK)
  Filter runs by execution status.

• withWarnings — boolean
  Only returns runs where warningCount > 0.

• withErrors — boolean
  Only returns runs where errorCount > 0.

• search — string
  Enables text-based search (only active if assignedTo is also set).

• triggerType — enum (USER, API, WEBHOOK, SCHEDULE, EVENT, FLOW, PUBLIC, TEST, EMAIL)
  Filter runs by how they were started.

• queuedOnDate — LocalDate (YYYY-MM-DD)
  Returns all runs queued on that specific calendar day.

• finishedEarlierThan — LocalDateTime (YYYY-MM-DDTHH:mm:ss)
  Returns all runs finished before this exact timestamp.

• rModelId — string
  Filter by relationship model ID.

• rObjectId — string
  Filter by relationship object ID.

All parameters are optional, except for non-admins who must specify at least one.

---

📄 Pagination

Use Pageable syntax:

?page=0
&size=20
&sort=finished,asc

Example

GET /runs?flowId={FLOW_ID}&page=0&size=20

---

📤 Example Response (Page)

{
  "content": [
    {
      "id": "run123",
      "caseId": 55,
      "status": "SUCCESS",
      "queued": "2024-01-17T12:00:00Z",
      "finished": "2024-01-17T12:05:00Z",
      "assignee": {
        "userId": 99,
        "groupId": null
      }
    }
  ],
  "pageable": { ... },
  "totalPages": 4,
  "totalElements": 72
}

---

🧪 Example Requests

Get runs assigned to me (requires Bearer Token)
GET /runs?assignedTo=me
Authentication: BEARER_TOKEN

Search runs
GET /runs?search=5501
Authentication: ApiKey your_api_key

Filter by flow & status
GET /runs?flowId={FLOW_ID}&status=COMPLETED
Authentication: ApiKey your_api_key

📅 Filter Runs by Queued Date

GET /runs?queuedOnDate=2024-02-15
Authentication: ApiKey your_api_key

• Matches all runs queued on 2024-02-15
• Equivalent to: 2024-02-15T00:00:00 → 2024-02-16T00:00:00

⏳ Filter Runs Finished Before a Timestamp

GET /runs?finishedEarlierThan=2024-03-01T12:00:00
Authentication: ApiKey your_api_key

• Returns all runs finished before 2024-03-01 12:00:00
• Useful for cleanup, reporting, or historical analysis

---

⚠️ Performance Notes

• When assignedTo=me is not set, the path field is excluded for performance.

---

🧯 Error Cases

Invalid filter input

HTTP 400
"Invalid filter argument ..."

Query execution error

HTTP 400
"Error during query execution at runs. Reason: ..."

/bots

/webhooks

/functions

UIs

/uis

Templates

/templates

Documents

/documents

/document-collections