Documents (DMS)

The Document Management System (DMS) REST API lets external systems upload, search, list, and retrieve documents through a versioned, resource-oriented surface. All endpoints live under /api/dms/public/v1/ and are protected by OAuth bearer tokens.

Authentication

Every /dms/public/ endpoint requires a valid bearer token. The controller validates the token's jpt (principal-type) claim and the caller's API license on every request. See Authentication to obtain a token, then send it as:

Authorization: Bearer <access_token>

Upload a document

Upload a new document. On success the endpoint returns 201 Created with a Location header that points at the newly created document, and a body containing the generated document ID.

HTTP/1.1 201 Created
Location: /api/dms/public/v1/documents/123456

{
  "documentId": 123456
}

Idempotency and duplicate detection

The upload endpoint uses header-based idempotency. Send an Idempotency-Key header containing a client-generated UUID with the request. If a request is replayed with the same key, the server returns 201 Created with the original documentId and a Location header pointing at the original document — no second document is created. The header is optional; omitting it means every request creates a new document, even if the metadata is identical.

Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6

The key must be a valid UUID; otherwise the request is rejected with 400 Bad Request. There is no content-based uniqueness check — category, type, and document number are not used to detect duplicates, and there is no 409 Conflict response from this endpoint.

Validation

The metadata part is a JSON object with category (required), type (required), documentNumber, documentName, description, and attributes (an object of attribute name → value), sent alongside the binary file in a multipart/form-data body.

Use Get categories and types and Get category/type attributes to discover valid values and required attributes before uploading.

Search documents

Search accepts its filter criteria as a JSON body rather than query parameters. Index attribute filters can exceed safe URL length limits (~2000 characters) and cannot be passed reliably as query parameters, so a POST body is used. Pagination remains in the query string.

POST /api/dms/public/v1/documents/search?page=1&pageSize=50

{
  "category": "Invoices",
  "type": "AP",
  "documentNumber": "INV-100234",
  "rangeFilter": "Last 6 months",
  "attributes": {
    "VendorCode": "ACME",
    "JobNumber": "J-1001"
  }
}

List documents

A plain GET on the collection returns an unfiltered listing of documents, paged with the same page and pageSize query parameters. Use search when you need to filter.

GET /api/dms/public/v1/documents?page=1&pageSize=50

Download a document

Downloads the document's raw binary content by its ID. The response is the file itself — not a JSON object — with Content-Type set from the file's extension and a Content-Disposition header carrying the original document name. Returns 404 Not Found when the document does not exist or its file content is unavailable.

Download by DMS number

Downloads a document's binary content looked up by its DMS document number instead of its internal document ID. If multiple documents share the same DMS number, the most recently created document is returned. Returns 400 Bad Request if dmsNumber is empty, and 404 Not Found if no document matches or its file content is unavailable.

Retrieve document metadata

Returns metadata for the document without downloading the document content itself. Useful when you only need to inspect index attributes, category, type, or creation details. Returns 404 Not Found when the document does not exist or is not visible to the caller.

Get categories and types

Returns every valid document category along with the types associated with it. Use this to populate category/type pickers or to validate values before calling upload or search.

{
  "categories": [
    {
      "category": "Invoices",
      "types": ["AP", "AR"]
    }
  ]
}

Get category/type attributes

Returns the index attributes configured for a specific category/type combination, including which attributes are required. Use this to build an upload form dynamically and to know which attribute values must be supplied so upload doesn't fail validation.

GET /api/dms/public/v1/documents/CategoryTypeAttributes?category=Invoices&type=AP

Rate limiting

All DMS public endpoints enforce a sliding-window rate limit of 100 requests per minute per client. The client is identified by the Bearer token; if no token can be resolved the caller's IP address is used as a fallback.

Every response includes the current rate-limit state:

When the limit is exceeded the server returns 429 Too Many Requests with a Retry-After header (seconds until the window resets) in addition to the headers above.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1750384200
Retry-After: 42

Errors

Errors are returned as RFC 7807 problem detail documents. See REST API Overview → Error responses for the common status codes and shape. DMS endpoints additionally use: