Getting started¶

Authenticate and access an HTTP API¶

To access the Bühler Maintenance API you need an Access Token for your plant. To obtain one, contact the Bühler COPC (Customer Operation Center) — for example by sending an email. COPC will provide you with a one-time link through which you can retrieve your Access Token.

This Access Token is a Bearer Token that is scoped to a specific plant. Include it in the Authorization header of every API request.

Upcoming change: The authentication mechanism for the Maintenance API will migrate to an OAuth 2.0 Client Credentials flow in a future release. Customers using an existing token will be notified before the switch, and this documentation will be updated accordingly.

The available endpoints, their parameters, and response schemas are documented on the API Reference page. You can use the retrieved Access Token directly on this documentation site by clicking on the "Authorize" button on the top right.

For more details about the authentication, check the authentication page.

Fetch jobs done from the Maintenance API¶

The following example shows how to retrieve a list of completed jobs for a specific plant in the production environment (please find the base URL on the API Reference page):

curl -X GET \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/jobs-done?startDate=2024-01-01&endDate=2024-12-31"

The response will be in JSON format and contains a paginated list of job records:

{
    "data": [
        {
            "id": "12345",
            "plantId": "{plantId}",
            "jobTitle": "Annual overhaul",
            "doneDate": "2024-06-15",
            "dueDate": "2024-06-01",
            "activityKind": "PREVENTIVE",
            "department": "Maintenance",
            "totalTimeUsedInHours": "4.5",
            "requiredPersonCount": 2,
            "isFinal": true,
            "asset": {
                "tagNumber": "TAG-001",
                "serialNumber": "SN-001",
                "externalReference": "EXT-001"
            },
            "workOrder": {
                "id": "WO-001",
                "remark": "Completed on schedule"
            },
            "carriedOutByUser": {
                "firstname": "John",
                "lastname": "Doe",
                "username": "john.doe"
            },
            "partsUsed": []
        }
    ],
    "page": 1,
    "totalPages": 1,
    "pageSize": 100
}

Fetch jobs planned¶

The following example shows how to retrieve planned maintenance jobs for a specific plant:

curl -X GET \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/jobs-planned?startDate=2024-01-01&endDate=2024-12-31"

Optional query parameters: assetTagNumber, assetSerialNumber, assetExternalReference.

Fetch assets¶

The following example shows how to retrieve registered assets at a specific plant:

curl -X GET \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/assets"

Fetch tasks from the Maintenance API¶

The following example shows how to retrieve pending tasks for a specific plant:

curl -X GET \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/tasks?taskStatus=PENDING"

The taskStatus parameter accepts the following values: PENDING, POSTPONED, NEED_CONFIRMATION, POSTPONEMENT_NEED_APPROVAL, NEED_APPROVAL, CLOSED, NOT_CLOSED.

Create a task¶

The following example shows how to create a new maintenance task:

curl -X POST \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"taskTitle": "Replace filter", "taskDescription": "Replace the main filter unit", "activityKind": "CORRECTIVE", "assignedToRole": "Maintenance Team", "priority": "HIGH", "createdDate": "2024-06-01", "dueDate": "2024-06-15", "incidentDate": "2024-06-01", "asset": {"tagNumber": "TAG-001"}}' \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/tasks"

The response will indicate the result of the operation:

{
    "status": "SUCCESS",
    "code": "SUCCESS",
    "message": null,
    "data": []
}

POST endpoints return a status of SUCCESS or ERROR. See the Errors page for details.

The activityKind, assignedToRole, and priority fields require company-specific values configured in ProPlant Office. See the Lookup Values page to learn how to retrieve them.

Apply an inventory stock level¶

The following example shows how to submit a stock level update for a spare part:

curl -X PUT \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"id": "PART-001", "quantity": 5, "unit": "PIECE", "remark": "Weekly restock", "isShort": false}' \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/parts/{partId}/stock-level"

Pagination¶

All Maintenance API GET endpoints return paginated results. Use the page and pageSize query parameters to navigate through results:

page: One-based page index. Defaults to 1.
pageSize: Number of records per page. Defaults to 100.

The response always includes totalPages indicating the total number of available pages.

Further information¶

{"environments":[],"pdf-download":true}