Document Archive

The Document Archive API manages all aspects of document archive data, including creation, update, validation, and soft deletion (termination). It enables external systems to store, retrieve, and manage documents with metadata, indexes, and thumbnails across the ERPx platform.

Purpose:
The ERPx API manages document archive, supporting create, read, update, and delete (CRUD) operations.

Base URL:
/v1/documents

Authentication:
All APIs require a Client ID and Client Secret.
Refer to the global authentication documentation for details.

System Parameters:
System parameters for this API are available in Online Help → Document Management → Document Archive → Fixed Registers → System Parameters.

Supported Methods

HTTP Method	Endpoint	Description	Limits & Notes
POST	`/v1/documents`	Create a single document record	Only 1 document per call. FileContent must be in base64.
GET	`/v1/documents`	Retrieve multiple documents	Returns array of documents. Supports pagination and filtering.
GET	`/v1/documents/{id}`	Retrieve single document data	Returns complete document information including base64 content. One document per call.
GET	`/v1/documents/{id}/thumbnail`	Retrieve document thumbnail	Returns thumbnail image. Supports custom width/height parameters.
PATCH	`/v1/documents/{id}`	Update document data	One document per call. Cannot update: FileName, FileContent, MimeType, Status, DocSize, Id, RevisionNo.
DELETE	`/v1/documents/{id}`	Terminate (soft-delete) a document	Changes status to ‘T’ (terminated). Does not permanently delete.

Swagger / Schema

Version v1

Method Details

Sample Request

{
  "companyId": "EN",
  "docType": "INVOICE",
  "title": "Invoice Q1 2025",
  "fileName": "invoice_q1.pdf",
  "fileContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBl...",
  "mimeType": "application/pdf",
  "indexes": [
    {
      "indexType": "COMPANY",
      "indexValue": "EN"
    },
    {
      "indexType": "PERIOD",
      "indexValue": "202501"
    }
  ]
}

{
  "companyId": "EN",
  "docType": "CONTRACT",
  "title": "Service Agreement 2025",
  "fileName": "contract_2025.pdf",
  "fileContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBl...",
  "mimeType": "application/pdf",
  "expiryDate": "2026-12-31T00:00:00.000Z",
  "description": "Annual service contract",
  "indexes": [
    {
      "indexType": "CUSTOMER",
      "indexValue": "CUST001"
    }
  ]
}

Limits & Notes

Mandatory fields: fileName, docType, fileContent, title
FileContent must be in base64 format - non-base64 content will be rejected
companyId is optional - if not provided, user’s default company is used
documentType must be a valid attribute value for the given client
indexes must have valid values for each index type configured for the document type
Client-supplied values ignored: docSize (calculated by API), revisionNo (set to 1), status (set to ‘N’), id (auto-generated GUID)
ExpiryDate validation: Must be today or in the future. If document type has expiry enabled and not provided, calculated by system
All indexes required: If document type requires 3 indexes, all 3 must be provided with valid values

Validation Rules for POST Method

POST_001 - User is not authorised

Element	Details
Scenario ID	POST_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

POST_002 - Unknown companyID

Element	Details
Scenario ID	POST_002
Scenario Name	Unknown companyID
HTTP Code	403
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	companyID does not exist
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

POST_003 - Document is created

Element	Details
Scenario ID	POST_003
Scenario Name	Document is created
HTTP Code	201
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	—
THEN	A new document is created
Example Error Message	RESPONSE: returns the created document

POST_004 - Client-supplied docSize is ignored

Element	Details
Scenario ID	POST_004
Scenario Name	Client-supplied docSize is ignored
HTTP Code	201
GIVEN	A new document needs to be created with posted docSize
WHEN	Calling the POST method of the API with “docSize”:100
BUT	docSize is ignored and calculated by the API
THEN	Document is created with system-calculated docSize
Example Error Message	RESPONSE: returns the created document with calculated docSize

POST_005 - Client-supplied revisionNo is ignored

Element	Details
Scenario ID	POST_005
Scenario Name	Client-supplied revisionNo is ignored
HTTP Code	201
GIVEN	A new document needs to be created with posted revisionNo
WHEN	Calling the POST method of the API with revisionNo:5
BUT	revisionNo is ignored and set as 1 by the API
THEN	Document is created with revisionNo = 1
Example Error Message	RESPONSE: returns the created document with revisionNo = 1

POST_006 - Client-supplied status is ignored

Element	Details
Scenario ID	POST_006
Scenario Name	Client-supplied status is ignored
HTTP Code	201
GIVEN	A new document needs to be created with posted status
WHEN	Calling the POST method of the API with status:C
BUT	status is ignored and set as N by the API
THEN	Document is created with status = ‘N’
Example Error Message	RESPONSE: returns the created document with status = ‘N’

POST_007 - Client-supplied id (GUID) is ignored

Element	Details
Scenario ID	POST_007
Scenario Name	Client-supplied id (GUID) is ignored
HTTP Code	201
GIVEN	A new document needs to be created with posted id
WHEN	Calling the POST method of the API with “id”: “81891c64-1cb0-4d40-9f6f-083fc8084fd0”
BUT	ID is ignored and new ID is created
THEN	Document is created with system-generated GUID
Example Error Message	RESPONSE: returns the created document with new GUID

POST_008 - Missing required field – fileName

Element	Details
Scenario ID	POST_008
Scenario Name	Missing required field – fileName
HTTP Code	400
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	fileName is missing or empty
THEN	Document is not created; 400 response is returned
Example Error Message	`{"code": 1010, "message": "The FileName field is required.\n"}`

POST_009 - Missing required field – docType

Element	Details
Scenario ID	POST_009
Scenario Name	Missing required field – docType
HTTP Code	400
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	DocType is missing or empty
THEN	Document is not created; 400 response is returned
Example Error Message	`{"code": 1010, "message": "The DocType field is required.\n"}`

POST_010 - Missing companyId uses default

Element	Details
Scenario ID	POST_010
Scenario Name	Missing companyId uses default
HTTP Code	201
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	companyID is missing
THEN	Document is created with user’s default companyID
Example Error Message	RESPONSE: returns the created document with default companyId

POST_011 - Missing required field – fileContent

Element	Details
Scenario ID	POST_011
Scenario Name	Missing required field – fileContent
HTTP Code	400
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	fileContent is missing or empty
THEN	Document is not created; 400 response is returned
Example Error Message	`{"code": 1010, "message": "The FileContent field is required.\n"}`

POST_012 - fileContent is not in base64

Element	Details
Scenario ID	POST_012
Scenario Name	fileContent is not in base64
HTTP Code	400
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	fileContent is not in base64 format
THEN	Document is not created; 400 response is returned
Example Error Message	`{"message": "The file content is not base64-encoded.", "messageType": "Information", "code": null, "path": null}`

POST_013 - Index is not a valid value

Element	Details
Scenario ID	POST_013
Scenario Name	Index is not a valid value
HTTP Code	400
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	One of the indexes has an invalid value
THEN	Document is not created; 400 response is returned
Example Error Message	`"notificationMessages": {"indexes": [{"code": 3010, "message": "Entered company 'TTT' does not exist"}]}`

POST_014 - Index is empty or missing

Element	Details
Scenario ID	POST_014
Scenario Name	Index is empty or missing
HTTP Code	400
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	One of the indexes is empty or missing
THEN	Document is not created; 400 response is returned
Example Error Message	`{"code": 1010, "message": "The IndexValue field is required.\n"}`

POST_015 - One of the required indexes is not passed

Element	Details
Scenario ID	POST_015
Scenario Name	One of the required indexes is not passed
HTTP Code	400
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	Document type requires 3 indexes but the last one was not provided
THEN	Document is not created; 400 response is returned
Example Error Message	`"notificationMessages": {"indexes": [{"code": 3010, "message": "You must enter a value for Resource"}]}`

POST_016 - Missing required field – title

Element	Details
Scenario ID	POST_016
Scenario Name	Missing required field – title
HTTP Code	400
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API
BUT	title is missing or empty
THEN	Document is not created; 400 response is returned
Example Error Message	`{"code": 1010, "message": "The Title field is required.\n"}`

POST_017 - ExpiryDate before today → reject

Element	Details
Scenario ID	POST_017
Scenario Name	ExpiryDate before today → reject
HTTP Code	400
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API with ExpiryDate in the past
BUT	ExpiryDate is before today
THEN	Document is not created; 400 response is returned
Example Error Message	`"notificationMessages": {"expiryDate": [{"code": 3010, "message": "The date in this field must be after {today}"}]}`

POST_018 - ExpiryDate equals today → accept

Element	Details
Scenario ID	POST_018
Scenario Name	ExpiryDate equals today → accept
HTTP Code	201
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API with ExpiryDate = today
BUT	—
THEN	Document is created
Example Error Message	RESPONSE: returns the created document

POST_019 - ExpiryDate in the future → accept

Element	Details
Scenario ID	POST_019
Scenario Name	ExpiryDate in the future → accept
HTTP Code	201
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API with ExpiryDate in the future
BUT	—
THEN	Document is created
Example Error Message	RESPONSE: returns the created document

POST_020 - ExpiryDate not passed with expiry enabled

Element	Details
Scenario ID	POST_020
Scenario Name	ExpiryDate not passed but document type has expiry date enabled
HTTP Code	201
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API without expiryDate
BUT	Document type has expiry date enabled
THEN	Document is created and expiry date is calculated by the system
Example Error Message	RESPONSE: returns the created document with system-calculated expiryDate

POST_021 - ExpiryDate passed with expiry enabled

Element	Details
Scenario ID	POST_021
Scenario Name	ExpiryDate passed and document type has expiry date enabled
HTTP Code	201
GIVEN	A new document needs to be created
WHEN	Calling the POST method of the API with expiryDate
BUT	Document type has expiry date enabled
THEN	Document is created and expiry date from payload is used
Example Error Message	RESPONSE: returns the created document with provided expiryDate

Sample Request

GET /v1/documents/6cf38e81-07d3-4a72-ae16-032eb29a3a09?companyId=EN

Sample Response

{
  "id": "6cf38e81-07d3-4a72-ae16-032eb29a3a09",
  "companyId": "EN",
  "docType": "INVOICE",
  "title": "Invoice Q1 2025",
  "description": "Quarterly invoice for services",
  "fileName": "invoice_q1.pdf",
  "fileContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBl...",
  "mimeType": "application/pdf",
  "docSize": 245678,
  "status": "N",
  "revisionNo": 1,
  "createdDate": "2025-11-25T10:30:00.000Z",
  "createdBy": "USER001",
  "indexes": [
    {
      "indexType": "COMPANY",
      "indexValue": "EN"
    },
    {
      "indexType": "PERIOD",
      "indexValue": "202501"
    }
  ]
}

Additional Parameters

Parameter	Value	Description	Data Type	Default Value
companyId	optional	Specify if you wish to retrieve a document that exists in a specific company or client.	string	user’s default company

Limits & Notes

One document per call
documentId must be a valid GUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
Returns complete document including base64-encoded fileContent
Document must belong to specified company or 404 error is returned

Validation Rules for GET Method (Single)

GET_001 - User is not authorised

Element	Details
Scenario ID	GET_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	Data from an existing document needs to be retrieved
WHEN	Calling the GET method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

GET_002 - Unknown companyID

Element	Details
Scenario ID	GET_002
Scenario Name	Unknown companyID
HTTP Code	403
GIVEN	Data from an existing document needs to be retrieved
WHEN	Calling the GET method of the API
BUT	companyID does not exist
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

GET_003 - Document is found

Element	Details
Scenario ID	GET_003
Scenario Name	Document is found
HTTP Code	200
GIVEN	Data from an existing document needs to be retrieved
WHEN	Calling the GET method of the API
BUT	—
THEN	200 response is returned together with the document information
Example Error Message	RESPONSE: Document information is retrieved

GET_004 - Document is not found

Element	Details
Scenario ID	GET_004
Scenario Name	Document is not found
HTTP Code	404
GIVEN	Data from an existing document needs to be retrieved
WHEN	Calling the GET method of the API
BUT	Document ID does not exist for the companyId
THEN	Document is not retrieved; 404 response is returned
Example Error Message	`{"code": 1040, "message": "Object of a following parameters [id: 6cf38e81-07d3-4a72-ae16-032eb29a3a05, companyId: EN] was not found"}`

GET_005 - Document belongs to a different company

Element	Details
Scenario ID	GET_005
Scenario Name	Document belongs to a different company
HTTP Code	404
GIVEN	Data from an existing document needs to be retrieved
WHEN	Calling the GET method of the API
BUT	Document exists but belongs to a different company
THEN	Document is not retrieved; 404 response is returned
Example Error Message	`{"code": 1040, "message": "Object of a following parameters [id: 6cf38e81-07d3-4a72-ae16-032eb29a3a09, companyId: NO] was not found"}`

GET_006 - Invalid id (GUID) format

Element	Details
Scenario ID	GET_006
Scenario Name	Invalid id (GUID) format
HTTP Code	400
GIVEN	Data from an existing document needs to be retrieved
WHEN	Calling the GET method of the API with malformed ID
BUT	ID is not a valid GUID format
THEN	Document is not retrieved; 400 response is returned
Example Error Message	`{"message": "Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).", "messageType": "Information", "code": null, "path": null}`

GET_007 - Invalid id is not in a GUID

Element	Details
Scenario ID	GET_007
Scenario Name	Invalid id is not in a GUID
HTTP Code	400
GIVEN	Data from an existing document needs to be retrieved
WHEN	Calling the GET method of the API with /v1/documents/11
BUT	ID is not a GUID (e.g., simple integer)
THEN	Document is not retrieved; 400 response is returned
Example Error Message	`{"message": "Unrecognised Guid format.", "messageType": "Information", "code": null, "path": null}`

Sample Request

GET /v1/documents?companyId=EN

GET /v1/documents?companyId=EN&doctype=INVOICE&limit=50

GET /v1/documents?companyId=EN&title=report&start=0&limit=20

GET /v1/documents?companyId=EN&doctype=CONTRACT&indexes=EN

GET /v1/documents?companyId=EN&withFileContent=true&limit=5

Sample Response

{
  "start": 0,
  "limit": 10,
  "count": 10,
  "total": 42,
  "items": [
{
  "companyId": "EN",
  "docType": "PERSONNEL",
  "mimeType": "image/tiff",
  "id": "6cf38e81-07d3-4a72-ae16-032eb29a3a09",
  "status": "N",
  "revisionNo": 1,
  "fileName": "Copy of 00100205.tif",
  "checkoutUserId": "",
  "lastUpdate": {
    "updatedAt": "2005-10-10T12:12:00.000",
    "updatedBy": "SYSEN"
  },
  "docSize": 0,
  "indexes": [
    { "sequenceNo": 1, "indexValue": "EN" },
    { "sequenceNo": 2, "indexValue": "87010101" }
  ],
  "title": "Copy of 00100205.tif",
  "description": ""
}
  ]
}

Query Parameters

Retrieves documents array based on parameters.

Parameter	Value	Description	Data Type	Default Value
companyId	optional	Company filter. If not provided, user’s default company is used.	string	user’s default
doctype	optional	Document type filter. Must be a valid attribute value.	string	none
title	optional	Title prefix filter (case-insensitive). Max 3998 characters. Matches documents whose titles start with this value.	string	none
indexes	optional	Indexes filter. Values concatenated and split by semicolon (;). Must match in exact order. Case-insensitive.	string	none
start	optional	Zero-based offset for pagination.	integer	0
limit	optional	Page size. Must be between 0 and 50000.	integer	10
withFileContent	optional	Include base64 file content for each document.	boolean	false

Limits & Notes

Returns array of document objects
Pagination envelope always includes: start, limit, count (items on this page), total (matching query)
doctype must be a valid attribute value configured in the system
Title matching: Prefix only (starts with), case-insensitive, no wildcards, spaces NOT trimmed
Indexes matching: Semicolon-separated (;), must be in exact order, case-insensitive, spaces NOT trimmed, empty segments treated as required empty values
Maximum limit: 50000 records per request
withFileContent impacts performance - use only when file content is needed

Validation Rules for GET Method (Multiple)

GET_001 - User is not authorised

Element	Details
Scenario ID	GET_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	Multiple documents need to be retrieved
WHEN	Calling the GET method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised”

GET_002 - Unknown companyID

Element	Details
Scenario ID	GET_002
Scenario Name	Unknown companyID
HTTP Code	403
GIVEN	Multiple documents need to be retrieved
WHEN	Calling the GET method of the API
BUT	companyID does not exist
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised”

U4 ERPx

Document Archive

The Document Archive API manages all aspects of document archive data, including creation, update, validation, and soft deletion (termination). It enables external systems to store, retrieve, and manage documents with metadata, indexes, and thumbnails across the ERPx platform.

Supported Methods

Swagger / Schema

Version v1

Method Details

Sample Request

Limits & Notes

Validation Rules for POST Method

Sample Request

Sample Response

Additional Parameters

Limits & Notes

Validation Rules for GET Method (Single)

Sample Request

Sample Response

Query Parameters

Limits & Notes

Validation Rules for GET Method (Multiple)