Skip to content
REST API

Loading Data with the Maximo REST API (MAS 9)

Updated on · VAGANET EAM

In short. The Maximo Manage REST API exposes each object structure at /maximo/api/os/<object structure>. You authenticate with the apikey header, create with POST, upsert with x-method-override: SYNC and group several records per call with x-method-override: BULK. Each row of a bulk call gets its own response: you have to read them one by one.

For large volumes and automation, the REST API (sometimes called the JSON API or the "NextGen REST API") is the most efficient channel for loading data into IBM Maximo Manage on MAS 9. Here is what you need to know to use it for a data init.

API key authentication

On MAS 9, create a dedicated integration user, give it the necessary security groups, then generate an API key for that user in Manage. Each request carries it in the header:

GET /maximo/api/os/mxapiasset?lean=1&oslc.select=assetnum,siteid,status&oslc.pageSize=10
Host: manage.your-domain.com
apikey: <API key>

The lean=1 parameter removes namespace prefixes from the JSON and makes responses easier to read. Never store the key in a shared file: it grants the integration user's rights to anyone who holds it.

Creating a record

POST /maximo/api/os/mxapiasset?lean=1
apikey: <API key>
Content-Type: application/json
properties: assetnum,siteid

{"assetnum": "PMP-1001", "siteid": "BEDFORD", "description": "Lift pump",
 "location": "BR300", "status": "NOT READY"}

The properties header tells Maximo to return the listed attributes of the created record, which lets you check the creation without a second call.

Updating and upserting

Updating a known record goes through its resource URI and the x-method-override: PATCH header. For a repeatable load, upsert is more practical:

POST /maximo/api/os/mxapiasset?lean=1
apikey: <API key>
x-method-override: SYNC
patchtype: MERGE
Content-Type: application/json

{"assetnum": "PMP-1001", "siteid": "BEDFORD", "description": "Lift pump no. 1"}

With SYNC, Maximo creates the record if it does not exist and updates it otherwise. With patchtype: MERGE, child objects absent from the message are kept instead of being deleted. This is the behavior of the MIF AddChange action (see the MIF guide).

Loading in bulk: grouped calls

One call per record is too slow beyond a few thousand rows. The x-method-override: BULK header lets you send an array of records in a single request, each with its own metadata:

POST /maximo/api/os/mxapiasset?lean=1
apikey: <API key>
x-method-override: BULK
Content-Type: application/json

[
  {"_data": {"assetnum": "PMP-1001", "siteid": "BEDFORD", "description": "Pump 1"},
   "_meta": {"method": "SYNC", "patchtype": "MERGE"}},
  {"_data": {"assetnum": "PMP-1002", "siteid": "BEDFORD", "description": "Pump 2"},
   "_meta": {"method": "SYNC", "patchtype": "MERGE"}}
]

The response is an array: one entry per record, with its own status. A call that returns 200 can contain rows in error. You must therefore read each entry, log the errors row by row and replay only those rows.

Throughput, batches and resume

  • Batch size: start small, measure, then increase as long as response time and error rate stay stable.
  • Parallelism: a few simultaneous streams speed up the load, but quickly saturate the Manage server and its rules (automation scripts, queues).
  • Resume: record which rows were acknowledged. After an interruption, resume at the first unacknowledged row; upsert guarantees that a resend creates no duplicate.
  • Window: load large volumes outside production hours, and warn the team that operates MAS.

Read-back to check

The API also serves to prove the result: a query filtered by oslc.where counts the records present and compares their attributes to the source file.

GET /maximo/api/os/mxapiasset?lean=1&oslc.where=siteid="BEDFORD"&count=1
apikey: <API key>

The guide quality control and reconciliation details this read-back.

Common REST API errors

  • 401 or 403: invalid key, or user without rights on the application or site.
  • Attribute ignored: missing from the object structure; add it or switch object structure.
  • Business error BMXAA…: Maximo rule (value outside the list, forbidden status, missing reference); the returned message names the attribute at fault.
  • Badly typed numbers and dates: send JSON numbers (not strings in local format with a comma) and ISO 8601 dates.
  • HTML response instead of JSON: authentication redirect (SSO) or intermediate gateway; the call must be retried, not counted as a success.

Frequently asked questions

How do you authenticate to the Maximo REST API in MAS 9?

With an API key generated in Manage for an integration user, passed in the apikey HTTP header. The key inherits the rights of that user: give it strictly the access needed to the relevant applications and sites.

Which object structure should you use with the REST API?

The MXAPI object structures (MXAPIASSET, MXAPIOPERLOC, MXAPIITEM, MXAPIWODETAIL…) are designed for the REST API. The classic MX object structures (MXASSET…) work too. In every case, the object structure must include the attributes you write.

Can you do an upsert with the Maximo REST API?

Yes. The x-method-override SYNC header creates or updates the record depending on its key; combined with patchtype MERGE, it keeps children absent from the message. It is the REST equivalent of the MIF AddChange action and the way to make a load repeatable.

How many rows should you send per bulk call?

There is no universal value: the right batch depends on record size, the rules Maximo runs and server capacity. Batches of a few dozen to a few hundred records are common; measure throughput and error rate on a test batch before settling on the size.

Load your Maximo data without silent errors

MAS9 checks your files against each environment's configuration, resumes an interrupted load without duplicates, then reads Maximo back to prove every row arrived.

Discover MAS9

More guides