Infor IDM Document Management API: Capabilities, Endpoints, and Constraints

TL;DR

• Bottom line: Infor IDM exposes a REST API through the ION API Gateway for document CRUD, search (via XQuery), and file upload/download. All calls require OAuth 2.0 bearer tokens via the ION API Gateway. Upload uses base64-encoded file content in JSON/XML payloads to POST /IDM/api/items.
• Key limit: Maximum file size is 2 GB per document; daily throughput caps range from 75,000 to 1.5M document operations depending on subscription tier (Essentials/Professional/Enterprise). [src1]
• Watch out for: Search responses include base64-encoded file content by default — a query returning 1,000 documents will attempt to return all file contents inline, creating enormous payloads. Always use separate /items/{pid}/resource/stream calls for file retrieval. [src7]
• Best for: Document lifecycle management (upload, version, search, download) within Infor CloudSuite ecosystems integrated with M3, LN, or other Infor ERP applications.
• Authentication: OAuth 2.0 via ION API Gateway using Resource Owner grant (service account accessKey/secretKey) for backend integrations; Authorization Code grant for interactive apps. [src5, src8]

System Profile

Infor Document Management (IDM) is a cloud-based enterprise content management (ECM) system that is part of the Infor OS platform. It provides document storage, versioning, search, and lifecycle management capabilities for all Infor CloudSuite applications (M3, LN, Syteline, etc.). IDM is accessed exclusively through the Infor ION API Gateway — there is no direct API endpoint outside the gateway. This card covers the cloud deployment; on-premises Infor OS deployments share the same REST API surface but have different infrastructure constraints. [src2, src3]

API Surfaces & Capabilities

IDM exposes a single REST API surface through the ION API Gateway. All endpoints are prefixed with the tenant-specific gateway URL. The API is organized around the Items resource (documents). [src2, src3]

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Expansion available via ION-S-DM add-on SKU in 15,000-unit increments. [src1]

Authentication

All IDM API calls are routed through the Infor ION API Gateway, which handles OAuth 2.0 authentication. There is no way to call the IDM API directly without going through the gateway. [src5, src8]

Authentication Gotchas

• Service account credentials are NOT user credentials: The Resource Owner grant uses accessKey as username and secretKey as password, NOT a human user's login. Generated from ION API Authorized Apps configuration. [src5, src8]
• The .ionapi credentials file contains all connection details: Download from ION Desk > ION API > Authorized Apps. Includes ci (client ID), cs (client secret), saak (access key), sask (secret key), iu (ION API base URL), pu (portal URL), oa (OAuth token endpoint). [src6]
• Idle refresh tokens expire after 30 days: If your integration is dormant for over 30 days, the refresh token is invalidated. Set grant lifetime to 0 for indefinite validity if needed. [src8]
• ION API Gateway adds latency: Every IDM API call goes through the gateway, adding 50-200ms overhead. Factor this into performance calculations. [src5]

Constraints

• No field-level projection on search results — search responses return full document metadata and base64-encoded file content by default; you cannot request only specific fields. [src7]
• Only major versioning (1.0, 2.0, etc.) — IDM does not support minor version increments; every check-in creates a new major version. [src2]
• Document types and attributes must be pre-configured — you cannot create document types or custom attributes via the API. An IDM administrator must configure them through the IDM Administration UI. [src4]
• All API calls must traverse the ION API Gateway — no direct IDM endpoint access is possible in cloud deployments. [src5]
• Check-out is exclusive — when a document is checked out, no other user or integration can modify it until check-in or discard. [src2]
• Base64 encoding inflates payload by ~33% — a 1.5 GB file becomes ~2 GB when base64-encoded, leaving almost no headroom under the 2 GB upload limit. [src1, src4]
• Subscription tier determines daily quotas — Essentials tier has 75,000 ops/day and 600 peak processing/min, which can be a bottleneck for integration-heavy workloads. [src1]

Integration Pattern Decision Tree

START — User needs to integrate with Infor IDM
|-- What's the operation?
|   |-- Upload single document
|   |   |-- File size < 20 MB? --> POST /IDM/api/items (synchronous)
|   |   |-- File < 2 GB? --> POST /IDM/api/items (background processing)
|   |   |-- File > 2 GB? --> Split or use IDM Utilities bulk import
|   |-- Search for documents
|   |   |-- Metadata only? --> GET /IDM/api/items/search + separate /resource/stream
|   |   |-- Large result set? --> Use $offset and $limit pagination
|   |-- Download document --> GET /IDM/api/items/{pid}/resource/stream
|   |-- Bulk import --> Use IDM Utilities File Import tool
|   |-- Event-driven --> Use ION Document Flows
|-- Authentication
|   |-- Backend integration --> Resource Owner grant with service account
|   |-- Web/mobile app --> Authorization Code grant
|   |-- Inside Infor OS --> SAML Bearer grant
|-- Error tolerance?
    |-- Zero-loss --> Attribute-based duplicate checks before upload
    |-- Best-effort --> Fire-and-forget with retry on 4xx/5xx

Quick Reference

Step-by-Step Integration Guide

1. Obtain ION API credentials

Navigate to Infor ION Desk > ION API > Authorized Apps. Create a new Backend Service type authorized app. Download the .ionapi credentials file containing client_id, client_secret, service account keys, and OAuth token endpoint URL. [src5, src6]

// The .ionapi file structure:
{
  "ci": "CLIENT_ID",
  "cs": "CLIENT_SECRET",
  "saak": "SERVICE_ACCOUNT_ACCESS_KEY",
  "sask": "SERVICE_ACCOUNT_SECRET_KEY",
  "iu": "https://{tenant}.ionapi.infor.com",
  "pu": "https://{tenant}.portal.infor.com",
  "oa": "https://{tenant}.portal.infor.com/IONSERVICES/oauth/token"
}

Verify: The .ionapi file downloads and contains all required fields.

2. Acquire OAuth 2.0 access token

Use the Resource Owner grant to exchange service account credentials for an access token. [src8]

TOKEN=$(curl -s -X POST "${TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "username=${SERVICE_ACCOUNT_ACCESS_KEY}" \
  -d "password=${SERVICE_ACCOUNT_SECRET_KEY}" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  | jq -r '.access_token')

Verify: echo $TOKEN returns a non-empty JWT string. Token valid for ~2 hours.

3. Upload a document to IDM

Post a document with metadata attributes, base64-encoded file content, document type (entityName), and ACL. [src4]

FILE_B64=$(base64 -w 0 invoice.pdf)
curl -s -X POST "${ION_API_BASE}/IDM/api/items" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "item": {
      "attrs": {"attr": [
        {"name": "Company_Number", "value": "1000"},
        {"name": "Invoice_Number", "value": "INV-2026-0042"}
      ]},
      "resrs": {"res": [{"filename": "invoice.pdf", "base64": "'${FILE_B64}'"}]},
      "acl": {"name": "Public"},
      "entityName": "Invoice"
    }
  }' | jq .

Verify: Response contains a pid (persistent item ID).

4. Search for documents by attributes

Use XQuery syntax on the search endpoint. Build queries using the IDM Query Builder UI first, then toggle "Enter Query Manually" to see generated XQuery. [src7]

curl -s -G "${ION_API_BASE}/IDM/api/items/search" \
  --data-urlencode "q=/Invoice[@Company_Number = '1000']" \
  --data-urlencode "\$offset=0" \
  --data-urlencode "\$limit=10" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json" | jq .

Verify: Response contains matching items with pid values.

5. Download document file content

Retrieve binary file content via the resource stream endpoint. [src7]

curl -s "${ION_API_BASE}/IDM/api/items/${DOCUMENT_PID}/resource/stream" \
  -H "Authorization: Bearer ${TOKEN}" \
  -o downloaded_document.pdf

Verify: Downloaded file matches original size and opens correctly.

6. Implement error handling and token refresh

Handle expired tokens (401), rate limits (429), and upload timeouts. Proactively refresh tokens before the ~2h expiry. [src5, src8]

# Re-acquire token on 401; back off on 429
# For uploads > 30 min timeout, consider chunking or IDM Utilities

Verify: Integration handles 401 by re-authenticating without manual intervention.

Code Examples

Python: Upload a Document to IDM

# Input:  .ionapi credentials file path, document file path, document type, attributes
# Output: Created document PID in IDM

import json, base64
import requests  # requests==2.31.0

def get_idm_token(ionapi_path):
    with open(ionapi_path) as f:
        creds = json.load(f)
    resp = requests.post(creds["oa"], data={
        "grant_type": "password",
        "username": creds["saak"], "password": creds["sask"],
        "client_id": creds["ci"], "client_secret": creds["cs"],
    })
    resp.raise_for_status()
    return creds["iu"], resp.json()["access_token"]

def upload_document(ionapi_path, file_path, entity_name, attributes, acl="Public"):
    base_url, token = get_idm_token(ionapi_path)
    with open(file_path, "rb") as f:
        file_b64 = base64.b64encode(f.read()).decode("utf-8")
    filename = file_path.rsplit("/", 1)[-1]
    payload = {"item": {
        "attrs": {"attr": [{"name": k, "value": v} for k, v in attributes.items()]},
        "resrs": {"res": [{"filename": filename, "base64": file_b64}]},
        "acl": {"name": acl}, "entityName": entity_name,
    }}
    resp = requests.post(f"{base_url}/IDM/api/items",
        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
        json=payload, timeout=1800)
    resp.raise_for_status()
    return resp.json()

result = upload_document("credentials.ionapi", "invoice.pdf", "Invoice",
    {"Company_Number": "1000", "Invoice_Number": "INV-2026-0042"})
print(f"Document created: PID={result.get('pid')}")

JavaScript/Node.js: Search and Download Documents

// Input:  .ionapi credentials, XQuery search string
// Output: Downloaded files saved to disk
// npm install [email protected]
const axios = require("axios");
const fs = require("fs");

async function getToken(creds) {
  const resp = await axios.post(creds.oa, new URLSearchParams({
    grant_type: "password", username: creds.saak, password: creds.sask,
    client_id: creds.ci, client_secret: creds.cs,
  }), { headers: { "Content-Type": "application/x-www-form-urlencoded" } });
  return resp.data.access_token;
}

async function searchAndDownload(ionapiPath, xquery, outputDir) {
  const creds = JSON.parse(fs.readFileSync(ionapiPath, "utf-8"));
  const token = await getToken(creds);
  const searchResp = await axios.get(`${creds.iu}/IDM/api/items/search`, {
    params: { q: xquery, $offset: 0, $limit: 50 },
    headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
  });
  for (const item of searchResp.data.items || []) {
    const fileResp = await axios.get(
      `${creds.iu}/IDM/api/items/${item.pid}/resource/stream`,
      { headers: { Authorization: `Bearer ${token}` }, responseType: "arraybuffer" });
    fs.writeFileSync(`${outputDir}/${item.filename || item.pid}`, fileResp.data);
  }
}

searchAndDownload("credentials.ionapi", "/Invoice[@Company_Number='1000']", "./downloads")
  .catch(console.error);

cURL: Quick API Test

# Input:  .ionapi credentials file
# Output: Token + document search results

CI=$(jq -r '.ci' credentials.ionapi)
CS=$(jq -r '.cs' credentials.ionapi)
SAAK=$(jq -r '.saak' credentials.ionapi)
SASK=$(jq -r '.sask' credentials.ionapi)
OA=$(jq -r '.oa' credentials.ionapi)
IU=$(jq -r '.iu' credentials.ionapi)

TOKEN=$(curl -s -X POST "$OA" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=$SAAK&password=$SASK&client_id=$CI&client_secret=$CS" \
  | jq -r '.access_token')

curl -s -G "$IU/IDM/api/items/search" \
  --data-urlencode "q=/Invoice[@Company_Number = '1000']" \
  --data-urlencode "\$offset=0" --data-urlencode "\$limit=5" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" | jq '.items | length'
# Expected: number of matching documents

Data Mapping

IDM Item Payload Structure

Data Type Gotchas

• All attribute values are strings: Even for date and numeric attributes, the API accepts and returns string values. XQuery comparison is lexicographic. [src4]
• Filename determines MIME type: IDM infers content type from the extension. Uploading a PDF as "document.txt" causes viewing issues. [src4]
• Base64 inflation reduces effective upload limit: A 1.5 GB file becomes ~2 GB after encoding, effectively capping API uploads at ~1.5 GB. [src1]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Search returning enormous payloads: Default search includes base64 file content. 500 docs at 5 MB each = 3+ GB response. Fix: Always use $limit; fetch file content separately via /items/{pid}/resource/stream. [src7]
• Token expiry mid-batch: Batch processing over 2h uses expired token. Fix: Check expiry before each batch; re-acquire proactively at 90% of lifetime. [src8]
• Missing required attributes on upload: Generic error "The document could not be created." Fix: Check Document Type config in IDM Administration for all required attributes before building payload. [src4]
• Checked-out document blocking integration: Stale checkout causes persistent 409. Fix: Monitor for stale checkouts; use discard checkout as admin override. [src2]
• Idle refresh token expiration: Monthly batch jobs find refresh token invalidated after 30 days. Fix: Set grant lifetime to 0 for indefinite validity, or implement keep-alive. [src8]
• ION API Gateway outage blocks all operations: Gateway is a single point of failure for IDM API. Fix: Dead letter queue for failed ops; replay on recovery. Monitor gateway health independently. [src5]

Anti-Patterns

Wrong: Fetching file content through search results

# BAD -- search returns base64 content for every match, creating enormous payloads
results = requests.get(f"{base_url}/IDM/api/items/search",
    params={"q": "/Invoice[@Company_Number = '1000']"}, headers=headers)
for item in results.json()["items"]:
    file_content = base64.b64decode(item["base64"])

Correct: Search metadata, then download files individually

# GOOD -- search with pagination, fetch files via stream endpoint
results = requests.get(f"{base_url}/IDM/api/items/search",
    params={"q": "/Invoice[@Company_Number = '1000']", "$offset": 0, "$limit": 50},
    headers=headers)
for item in results.json()["items"]:
    file_resp = requests.get(
        f"{base_url}/IDM/api/items/{item['pid']}/resource/stream", headers=headers)
    with open(f"downloads/{item['filename']}", "wb") as f:
        f.write(file_resp.content)

Wrong: Uploading large files without timeout handling

# BAD -- no timeout, no retry for large files
requests.post(f"{base_url}/IDM/api/items", json=payload_500mb, headers=headers)

Correct: Handle timeouts and implement retry logic

# GOOD -- explicit timeout matching IDM's 30-min limit, with retry
import time
def upload_with_retry(url, payload, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            resp = requests.post(url, json=payload, headers=headers, timeout=1800)
            resp.raise_for_status()
            return resp.json()
        except requests.Timeout:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt * 10)
                headers["Authorization"] = f"Bearer {get_fresh_token()}"
            else:
                raise

Wrong: Hardcoding document type attributes

# BAD -- attribute names and entityName are case-sensitive
payload = {"item": {"attrs": {"attr": [
    {"name": "Company", "value": "1000"}]},
    "entityName": "invoice"}}

Correct: Validate against IDM configuration schema

# GOOD -- validate attribute names and entityName against known schema
DOCUMENT_TYPES = {"Invoice": {"required": ["Company_Number", "Invoice_Number"]}}
def build_payload(entity_name, attrs, filename, file_b64):
    schema = DOCUMENT_TYPES.get(entity_name)
    if not schema:
        raise ValueError(f"Unknown document type: {entity_name}")
    missing = [a for a in schema["required"] if a not in attrs]
    if missing:
        raise ValueError(f"Missing required attributes: {missing}")
    return {"item": {"attrs": {"attr": [{"name": k, "value": v} for k, v in attrs.items()]},
        "resrs": {"res": [{"filename": filename, "base64": file_b64}]},
        "acl": {"name": "Public"}, "entityName": entity_name}}

Common Pitfalls

• Confusing Infor IDM with ForgeRock IDM: Completely different products. Infor IDM is ECM; ForgeRock IDM is identity management. Fix: Always specify "Infor Document Management" or "Infor OS IDM" in searches. [src2]
• Not accounting for base64 inflation: 1.5 GB file becomes ~2 GB encoded, hitting the limit. Fix: Calculate encoded size (original * 1.37) before upload. For near-limit files, use IDM Utilities. [src1]
• Assuming instant document availability after upload: Large files (>20 MB) are processed async. Fix: Poll for document availability. Don't immediately search for just-uploaded documents. [src1]
• Using Copy Document for large files: Copy has separate 50 MB limit. Fix: Use standard upload API for files > 50 MB. [src1]
• Not paginating search results: Unbounded search can return thousands of docs with base64 content. Fix: Always include $offset and $limit. Process in batches of 50-100. [src7]
• Relying on search for real-time change detection: Search indexes have a short delay. Fix: Store returned PID and query by PID directly for confirmation. [src2]

Diagnostic Commands

# Parse .ionapi file and acquire token
CI=$(jq -r '.ci' credentials.ionapi)
CS=$(jq -r '.cs' credentials.ionapi)
SAAK=$(jq -r '.saak' credentials.ionapi)
SASK=$(jq -r '.sask' credentials.ionapi)
OA=$(jq -r '.oa' credentials.ionapi)
IU=$(jq -r '.iu' credentials.ionapi)

TOKEN=$(curl -s -X POST "$OA" \
  -d "grant_type=password&username=$SAAK&password=$SASK&client_id=$CI&client_secret=$CS" \
  -H "Content-Type: application/x-www-form-urlencoded" | jq -r '.access_token')
echo "Token length: ${#TOKEN} (should be >100)"

# Test IDM API connectivity
curl -s -o /dev/null -w "%{http_code}" "$IU/IDM/api/items/search" \
  -H "Authorization: Bearer $TOKEN" \
  -G --data-urlencode "q=/*" --data-urlencode "\$limit=1"

# Check document count for a specific type
curl -s -G "$IU/IDM/api/items/search" \
  --data-urlencode "q=/Invoice" --data-urlencode "\$limit=0" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" | jq '.totalCount'

# Verify specific document exists
curl -s "$IU/IDM/api/items/${DOCUMENT_PID}" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  | jq '{pid: .pid, entityName: .entityName, version: .version}'

Version History & Compatibility

Infor follows a rolling release model for Infor OS. Breaking changes are announced through release notes with one major release cycle (~6-12 months) of advance notice. The IDM REST API does not use formal version numbering. [src2]

When to Use / When Not to Use

Important Caveats

• Subscription tier dramatically affects daily quotas: Essentials allows only 75,000 ops/day with 600 peak/min, while Enterprise allows 1.5M/day with 2,000/min. Size your integration accordingly. [src1]
• The IDM REST API does not have formal versioning — endpoints can change between Infor OS releases without a version increment. Always test when upgrading. [src2]
• On-premises Infor OS deployments share the same API surface but may have different infrastructure constraints. This card covers cloud deployments specifically. [src2]
• ION API Gateway availability is a hard dependency for all IDM operations. Gateway maintenance windows affect integrations. [src5]
• Document type configuration must be done via the IDM Administration UI — no API for schema management. Changes may require integration code updates. [src4]