How to Search and Upload Documents with the Infor IDM REST API
how to search and upload documents with Infor IDM REST API
Also searched as
- Infor IDM API upload document attach to ERP record
- IDM items search $query entity attribute
- Infor Document Management REST API example
- ION API IDM resources create item
Short answer
Infor Document Management (IDM) exposes REST services through ION API under the IDM path of your tenant. You search items with a $query expression written against an entity and its attributes, read the returned resource links to fetch the file, and create new items with a multipart request that carries an XML description of the entity and attributes plus the file stream.
Applies to: Infor Document Management 10.x and the cloud IDM service reached through ION API; entity and attribute names are defined in your own IDM configuration
Search for and upload an IDM document
- 1Get an access token from ION API using a service account whose security roles include IDM access (see the .ionapi guide).
- 2Open IDM Administration and note the exact entity name (for example Invoice or PurchaseOrder) and the attribute names you will filter on. They are case sensitive in the query.
- 3Search with GET on the IDM items search resource under your tenant, passing a $query such as /Invoice[@PONumber = "4500012345"], plus $offset and $limit for paging.
- 4Read the response: each item lists attributes, a pid (the permanent id) and a resources block with links for the file stream. Keep the pid, not a list position.
- 5Download the file by following the resource link with the same bearer token and an Accept header that matches the file type.
- 6To upload, POST a multipart request to the items resource with an XML part that describes the entity name, the attribute values and the file name, and a second part holding the bytes.
- 7Check the HTTP status and the returned pid. Search for the item again to confirm the attributes were stored and the file opens.
- 8Set up the ERP side link, for example Drill Back or document attach, so users find the file from the transaction.
Writing the $query expression
IDM queries use an XPath-like syntax rooted at the entity. A filter on one attribute reads /Invoice[@Supplier = "ACME"], and several conditions combine with and or or. Dates are compared in the format defined for the attribute, and wildcard matching uses the asterisk. Only attributes that are marked as searchable in the entity definition can be used, so an unexpected empty result often means the attribute is not indexed.
Always page. The server caps the page size, so loop on $offset until a page returns fewer than $limit items. Sorting is supplied with a separate parameter, and the result order is not guaranteed unless you request it. Test a query first in the IDM Desktop or web search screen, because the expression mirrors what that screen builds.
GET https://mingle-ionapi.inforcloudsuite.com/ACME_PRD/IDM/api/items/search?$query=/Invoice[@PONumber = "4500012345"]&$offset=0&$limit=50 Authorization: Bearer <token> Accept: application/json
Uploading a new item
A create call is a multipart POST. The first part is an XML document naming the entity and listing each attribute with its value. The second part is the file. Mandatory attributes defined on the entity must be present or the request fails with a validation message, so compare your XML to the entity in IDM Administration before debugging anything else.
Large files may be rejected by a size limit in the gateway or the IDM configuration. If uploads over a few tens of megabytes fail while small ones work, check limits rather than the payload format. After creation, the item may pass through a workflow or lifecycle state, so a search immediately afterward can briefly miss it if indexing lags.
<?xml version="1.0" encoding="UTF-8"?>
<item xmlns="http://www.infor.com/idm">
<entityName>Invoice</entityName>
<attrs>
<attr><name>PONumber</name><value>4500012345</value></attr>
<attr><name>Supplier</name><value>ACME</value></attr>
</attrs>
<resrs><res><filename>inv-4500012345.pdf</filename></res></resrs>
</item>Linking documents back to ERP records
For M3, SyteLine and LN, the link from a transaction to an IDM document is built through attributes that carry the business keys, such as order number or supplier, plus the Drill Back or attachment configuration in the ERP. If you store the right keys on upload, users and APIs can find the file from the record without any extra mapping table.
Plan the attribute model before you bulk load. Changing a key later means re-indexing or re-uploading, and inconsistent values (leading zeros, different case) make exact match queries miss documents that look identical on screen.
Common pitfalls
- !Using an attribute that is not searchable. The query returns nothing and no error, so check the entity definition first.
- !Relying on list position in results instead of the pid, which breaks as new items arrive.
- !Forgetting to page. Only the first page is returned, and a loop that stops on the first page silently drops documents.
- !Mismatched case or leading zeros in key values between ERP and IDM, which defeats exact match lookups.
- !Calling IDM with a token from a service account that has no IDM role, which yields 403 rather than empty results.
How an ERP-grounded AI assistant handles this
Document questions such as show me the signed invoice for this purchase order are really an IDM query keyed by ERP attributes. A grounded assistant can resolve the order number from the ERP, build the $query for the right entity and return the document link, while respecting IDM security. Netray custom builds can also index document text for private retrieval, with the ERP and IDM roles still applied.
Frequently asked questions
Which URL path does the IDM REST API use?
In cloud tenants you call it through the ION API gateway, using the base URL from your .ionapi file, then your tenant id, then the IDM path and the items resources. Exact prefixes differ by deployment, so confirm in the ION API documentation for your release.
Why does my IDM search return zero items?
Common causes are a wrong entity name, a non-searchable attribute, case or formatting differences in the value, and a service account without access to that entity. Run the same filter in the IDM search screen to see whether it returns results there.
Can I upload a file without any attributes?
Not usually. The entity definition marks some attributes as mandatory and the create request fails validation if they are missing. Supply every mandatory attribute and a file name in the XML part of the multipart request.
Is the pid the same as the item id shown in the IDM screen?
The pid is the permanent identifier IDM assigns to an item and is the stable reference for API calls. Display ids and version numbers can change as items are revised, so store the pid when you link to it from another system.
Related
How to Attach and View Documents in M3 with IDM
Infor Document Management (IDM) attaches to M3 through key-based document classes: each document is filed against a document class that maps to a specific M3 program and key fields (order number, item number, customer number), so the paperclip or document icon on that M3 panel shows only documents whose stored key values match the record you are viewing.
How-toHow to Create an .ionapi File and Service Account in Infor OS
An .ionapi file is a JSON credentials file you download from ION API after registering an Authorized App of type Backend Service and creating a service account for it. It carries the tenant, client id, client secret, the token and authorization endpoints, and the service account keys that your scripts or integrations use to request an OAuth 2.0 access token.
Error fixFix a 401 Unauthorized error from Infor ION API
A 401 from ION API almost always means the credentials in the .ionapi file no longer match what ION API Gateway expects - not that the password is simply wrong. Check whether the Authorized App or service account behind the file was revoked, regenerated, expired, or issued for a different tenant, then re-test with a direct OAuth2 client_credentials call before touching any calling code.
Error fixSyteLine EDI or BOD inbound document fails to create a sales order
An inbound EDI 850 or ION SyncSalesOrder / ProcessSalesOrder BOD that does not turn into a SyteLine order almost always fails validation before it ever reaches order entry logic - most often a customer, ship-to, or item cross-reference that the mapping expects but SyteLine does not have on file. Check the EDI translator's error log or the ION BOD document inbox first; the rejection reason is usually recorded there, not just a generic SyteLine error.
Error fixDiagnose and fix a failed BOD document flow in ION Desk
A Document Flow showing Failed in ION Desk means a BOD (Business Object Document) stopped either at schema validation, at the mapping step, or at the target application. Open the failed instance's detail to see the exact failing element, fix the source data or mapping, then use Resubmit rather than re-triggering the original transaction to avoid duplicates.
How-toHow to query Infor Data Lake with Compass SQL
Compass is the SQL query layer in Infor OS for querying Infor Data Lake, where flattened copies of BODs published over ION are stored by Noun and Verb. Open a Compass SQL Workbench tab, browse the schema for the correct table, and run a filtered SELECT rather than pulling the full history, since Data Lake tables can hold years of append-only data.
AI for ERPAI Agents Over Infor ION API, BODs, and the Infor Data Lake
Build AI agents on Infor ION API Gateway, BODs, and Data Lake, alongside or instead of Infor's own GenAI features, with your choice of model and hosting.
AI for ERPAI for Infor M3: A Practical Path from MI Programs to a Private Assistant
Add grounded AI to Infor M3: natural-language answers over MI programs and MEC, agents for distribution and manufacturing, on-prem or private cloud in Europe.
AI for ERPAI for Infor SyteLine and CloudSuite Industrial
Add grounded AI to Infor SyteLine or CloudSuite Industrial: natural-language answers, agents over IDOs and ION, on-prem or CloudSuite deployment.
Stuck on Infor Document Management (IDM)?
Talk to engineers who work inside Infor Document Management (IDM) every week, and who build private AI that answers these questions from your own ERP data.