Task Api

The Localion Navigator provides an HTTP-API which allows customers to dispatch tasks to the Localion Navigator and to track their delivery, confirmation and completion. A task carries a target location and is delivered to the assigned users as a push notification which the Localion Navigator opens in the requested mode.

Authentication

The Task Api is secured with OAuth2. LOGIBALL provides you with a API key that you can use to obtain access tokens. If you have not received it yet, please contact the support at navigation@localion.de.

Every request is authorized in two steps:

Request a short-lived access token from the token endpoint using your key.
Send that access token as a Bearer token in the Authorization header of each API request.

The access token is valid for one hour and can be reused until it expires; request a new one afterwards.

Example token request (the token endpoint is the same for every customer; only the key differs):

curl --location --request POST 'https://localion-navigator-tasks-prod.auth.eu-central-1.amazoncognito.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <your-key>' \
--data-urlencode 'grant_type=client_credentials'

Example response:

{
    "access_token": "<your-key>",
    "expires_in": 3600,
    "token_type": "Bearer"
}

The access_token is then used for every API request:

--header 'Authorization: Bearer <your-key>'

URL and endpoints

This API is accessible through the URL: https://customerapi.navigator.localion.de/manageTasks.

The following endpoints are provided:

/tasks (POST) – create a task
/tasks (GET) – list the current tasks of your group
/tasks/{taskId} (DELETE) – delete a task
/tasks/{taskId}/notifications (GET) – notifications sent for one task
/notifications (GET) – notifications sent for all of your tasks
/tasks/status (GET) – your tasks with their received, confirmed and completed users per task

Create a Task

Creates a task and dispatches it to the assigned users as a push notification. Use the /tasks endpoint with the POST method.

Body

The request body is a JSON object:

Key	Type	Description	Required
assignedUsers	List of String	The user names of the Navigator users the task is dispatched to. Must not be empty.	Yes
target	Object	The destination of the task (see below).	Yes
targetMode	String	How the Navigator presents the target: `destination`, `routing` or `navigation`.	Yes
notificationText	String	The text shown in the push notification. A generic text is used if omitted.	No

The target object:

Key	Type	Description	Required
displayPointLatitude	Double	The latitude of the decimal coordinate shown on the map (WGS84)	Yes
displayPointLongitude	Double	The longitude of the decimal coordinate shown on the map (WGS84)	Yes
entryPointLatitude	Double	The latitude of the decimal coordinate the route leads to (WGS84)	No
entryPointLongitude	Double	The longitude of the decimal coordinate the route leads to (WGS84)	No
title	String	A short title for the destination	No
description	String	A more detailed description of the destination	No

The display point is the position the target is shown at on the map, the entry point is the position a route or navigation leads to — for example the access road of a site whose marker sits in the middle of the property. Each entry point coordinate can be omitted on its own and then falls back to the matching display point coordinate.

The targetMode determines how the Navigator presents the target once the user opens the task:

destination – the target is shown on the map
routing – a route to the target is calculated
navigation – turn-by-turn navigation to the target is started

Result

On success the response has status code 201 and returns the id and the version of the created task:

{
    "taskId": "9c1e0000-0000-5000-8000-000000000001",
    "taskVersion": 1
}

A status code 400 means the request body is invalid — this also covers assigned users that are not members of your group; the response names the rejected users. A status code 403 means the token is not authorized for a group.

Example Request:

curl --location --request POST 'https://customerapi.navigator.localion.de/manageTasks/tasks' \
--header 'Authorization: Bearer <your-key>' \
--header 'Content-Type: application/json' \
--data '{
    "assignedUsers": ["driver1", "driver2"],
    "target": {
        "displayPointLatitude": 51.5,
        "displayPointLongitude": 7.25,
        "entryPointLatitude": 51.6,
        "entryPointLongitude": 7.35,
        "title": "Kunde A"
    },
    "targetMode": "navigation",
    "notificationText": "Bitte Ziel anfahren"
}'

List Tasks

Returns the current tasks of your group, each in its latest version, paginated. Use the /tasks endpoint with the GET method.

Parameters

Query parameter	Description	Required
limit	The maximum number of tasks per page, `1` to `200`. Defaults to `200`.	No
nextToken	The token from the previous response to fetch the next page.	No

Result

A JSON object containing one page of tasks. If more pages exist, the response carries a nextToken; repeat the request with it until the response contains no nextToken. A page may contain fewer tasks than limit:

{
    "tasks": [
        {
            "taskId": "9c1e0000-0000-5000-8000-000000000001",
            "taskVersion": 1,
            "groupName": "your-group",
            "assignedUsers": ["driver1", "driver2"],
            "target": {
                "displayPointLatitude": 51.5,
                "displayPointLongitude": 7.25,
                "entryPointLatitude": 51.6,
                "entryPointLongitude": 7.35,
                "title": "Kunde A"
            },
            "targetMode": "navigation",
            "notificationText": "Bitte Ziel anfahren",
            "createdAt": "2026-07-23T08:00:00.000Z"
        }
    ]
}

Example Request:

curl --location --request GET 'https://customerapi.navigator.localion.de/manageTasks/tasks' \
--header 'Authorization: Bearer <your-key>'

Delete a Task

Deletes a task and notifies the assigned users that it was cancelled. Use the /tasks/{taskId} endpoint with the DELETE method.

Parameters

The id of the task to delete is part of the URL:

https://customerapi.navigator.localion.de/manageTasks/tasks/{taskId}

Result

On success the response has status code 200 and reports how many versions of the task were removed:

{
    "taskId": "9c1e0000-0000-5000-8000-000000000001",
    "deletedVersions": 1
}

A status code 404 means that no task with this id exists in your group.

Example Request:

curl --location --request DELETE 'https://customerapi.navigator.localion.de/manageTasks/tasks/9c1e0000-0000-5000-8000-000000000001' \
--header 'Authorization: Bearer <your-key>'

Task Notifications

Returns the notifications that were sent for your tasks so you can see which users were reached, paginated. Use the /notifications endpoint for all of your tasks, or the /tasks/{taskId}/notifications endpoint for a single task, with the GET method. Both endpoints accept the limit and nextToken query parameters described under List Tasks; if more pages exist, the response carries a nextToken.

One notification is created per user each time a task is created, updated or cancelled.

A notification expires three days after it was sent. If the user's device is offline for longer, the push is discarded by Android or iOS and the notification stays in the sent state. The task itself is not lost: the Localion Navigator reconciles its task list with the server as soon as it is online again.

Field	Description
notificationId	The unique id of the notification
taskId	The task the notification belongs to
taskVersion	The task version the notification was sent for
eventType	`created`, `updated` or `cancelled`
status	`sent` when delivered, `processed` once the user's app acknowledged it
targetUser	The user the notification was sent to
targetDevice	The Firebase installation id of the app the notification was sent to
createdAt	When the notification was sent

Result

{
    "notifications": [
        {
            "notificationId": "1f2e0000-0000-5000-8000-000000000009",
            "taskId": "9c1e0000-0000-5000-8000-000000000001",
            "taskVersion": 1,
            "eventType": "created",
            "status": "processed",
            "targetUser": "driver1",
            "targetDevice": "6f0b1c8e-3d2a-4e5f-9a1b-2c3d4e5f6a7b",
            "createdAt": "2026-07-23T08:00:05.000Z"
        }
    ]
}

Example Request:

curl --location --request GET 'https://customerapi.navigator.localion.de/manageTasks/tasks/9c1e0000-0000-5000-8000-000000000001/notifications' \
--header 'Authorization: Bearer <your-key>'

Task Status Overview

Returns your tasks together with, for each task, the users who received the notification, the users who confirmed it and the users who completed the task. Use the /tasks/status endpoint with the GET method. It combines the task, its notifications and its completions in a single call. The endpoint accepts the limit and nextToken query parameters described under List Tasks; if more pages exist, the response carries a nextToken.

Field	Description
receivedUsers	Users whose device received the task notification
confirmedUsers	Users whose app acknowledged the notification
successfullyCompletedUsers	Users who reported that they reached the target
unsuccessfullyCompletedUsers	Users who reported that the target could not be reached

receivedUsers and confirmedUsers are cumulative stages of the delivery: a user can only confirm a notification they received. Completion is reported independently once the user has finished the task, and each user appears in at most one of the two completion lists. Once a user has reported either outcome, the task is no longer shown to them in the Localion Navigator.

Result

{
    "tasks": [
        {
            "taskId": "9c1e0000-0000-5000-8000-000000000001",
            "taskVersion": 1,
            "groupName": "your-group",
            "assignedUsers": ["driver1", "driver2"],
            "target": {
                "displayPointLatitude": 51.5,
                "displayPointLongitude": 7.25,
                "entryPointLatitude": 51.6,
                "entryPointLongitude": 7.35,
                "title": "Kunde A"
            },
            "targetMode": "navigation",
            "notificationText": "Bitte Ziel anfahren",
            "createdAt": "2026-07-23T08:00:00.000Z",
            "receivedUsers": ["driver1", "driver2"],
            "confirmedUsers": ["driver1", "driver2"],
            "successfullyCompletedUsers": ["driver1"],
            "unsuccessfullyCompletedUsers": ["driver2"]
        }
    ]
}

Example Request:

curl --location --request GET 'https://customerapi.navigator.localion.de/manageTasks/tasks/status' \
--header 'Authorization: Bearer <your-key>'