IBM Maximo REST API Guide – Bulk operations

With Maximo RESTful JSON API, you can process multiple resources with multiple operations in a single transaction. The bulk process is supported only by using collection URLs. You can use the POST method and x-method override value BULK in the header.

The multiple resources and operations are provided in the message body with a JSON array. Each resource is like the object used to create mbo. It contains data and _action attribute which indicates operation like add, update or delete.

Operation	Data Object Example
CREATE	`{"assetnum": "test-5", "siteid": "BEDFORD", "description": "TS test 5","_action":"Add"}`
UPDATE	`{"href": "...", "description": "New description","_action":"Update"}`
DELETE	`{"href": "...", "_action": "Delete"}`

Unless there is a syntax type of error in your JSON data for bulk load, you will always get a response code of 200. However, you need to process the response to determine which resources were updated successfully.

Multiple Resources Creation with BULK

You can create multiple resources in a single transaction. As the regular creation, each of the resources go through the validation process. And the response for each of the resources are shown in response JSON.

NOTE: The processing performs a Commit for each resource.

POST oslc/os/mxapiasset?lean=1
X-method-override: BULK

Post body:

[
  {
    "assetnum": "test-1",
    "siteid": "BEDFORD",
    "description": "TS test 1",
    "_action": "Add"
  },
  {
    "assetnum": "test-2",

Response JSON:

[
  {
    "_responsemeta": {
      "status": "201",
      "Location": "oslc/os/mxapiasset/_VEVTVC0xL0JFREZPUkQ-"
    }
  },
  {
    "_responsemeta": {

If the first asset failed the validation process by having the invalid site, the http response code is still be 200. However, the error message similar to the messages in the following example is shown in the response:

POST oslc/os/mxapiasset?lean=1
X-method-override: BULK

Post body:

[
  {
    "assetnum": "test-3",
    "siteid": "BEDFORDXXYY",
    "description": "TS test 1",
    "_action": "Add"
  },
  {
    "assetnum": "test-4",

Response JSON:

[
  {
    "_responsedata": {
      "Error": {
        "errorattrname": "siteid",
        "extendedError": {
          "moreInfo": {
            "href": "oslc/error/messages/BMXAA4153E"
          }

The first asset errored out because of invalid site and hence returns a 400 with an error message. The second asset returns a 201 with the URI to the newly created asset resource. The overall HTTP response code would still be 200. In the above case, even if both the asset json faced a business validation error, the overall response code would still be 200. The only cases you will see an error status is when the request is structurally invalid (say invalid json) or maybe for some request level error like the authentication failed.

We also support bulk change for actions, for example, change status as shown below: For more info about Actions, see: Action

POST /oslc/os/mxapiwodetail?action=wsmethod:changeStatus
X-method-override: BULK

Post body:

[
  {
    "status": "APPR",
    "href": "..."
  },
  {
    "status": "INPRG",
    "href": "..."
  }

The response format has not changed.

Multiple Operations with BULK

The examples in first section shows the creation of multiple assets using the BULK processing. You can also use BULK to perform a mix of create, update and delete of asset resources in a single transaction.

To support this, simply change the _action value from Add to Update or Delete

Operation	Data Object Example
CREATE	`{"_action":"Add"}`
UPDATE	`{"_action":"Update"}`
DELETE	`{"_action": "Delete"}`
MERGE	`?`

Below is an example JSON data that will

Update an asset with a ‘New Description’
Create a new asset (test-100)
Delete an asset

POST oslc/os/mxapiasset?lean=1
x-method-override: BULK

Post body:

[
  {
    "description": "New Description",
    "_action": "Update"
  },
  {
    "assetnum": "test-100",
    "siteid": "BEDFORD",
    "description": "New Asset 100",

As with the Creation example earlier in this section, the response code will be a 200 but you must examine the response information in the response JSON body to determine if processing of each asset was successful or not.

allornothing header

The default functionality for the bulk post is that it will update those which it can. The result will be returned as an array containing the ones which succeeded and the ones which had failed. allornothing header can be used to control whether BULK commits at the end. When the value is set to 1, if any of the the updates in the bulk post fails, all updates will not go through resulting in no records updated.

Here is the example of allornothing value is 1.

POST oslc/os/mxapiasset?lean=1
x-method-override: BULK
allornothing: 1

Post body:

[
  {
    "description": "New Description",
    "_action": "Update"
  },
  {
    "assetnum": "test-100",
    "siteid": "BEDFORD",
    "description": "New Asset 100",

In this case, assume the add action fails due to some reason, the Update and Delete action will also be cancelled. No changes will be committed to system. The changes will only be made if all updates passes.

Edit this page on GitHub

Create, Update and Delete (POST/PATCH/DELETE): Delete

Create, Update and Delete (POST/PATCH/DELETE): Sync