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. |
| POST | /documents/element-type | Retrieve documents relevant to a workflow record by element type | Returns only documents defined as relevant for the element type. Supports workflow key transformation to Document Archive keys when required. |
| 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. |
POST /documents/element-type
Use this method to retrieve documents associated with a workflow record based on its element type and business context.
- Returns only documents defined as relevant for the element type.
- Supports transformation of workflow keys to Document Archive keys when required.
Refer to the OpenAPI schema below for request and response details.
Swagger / Schema
Version v1
document_archive v1 API endpoints
/v1/document-revisions
/v1/document-revisions/{id}
/v1/document-revisions/{id}/{revisionNo}
/v1/document-revisions/{id}/{revisionNo}/thumbnail
/v1/documents
/v1/documents/element-type
/v1/documents/{id}
/v1/documents/{id}/thumbnail
/v1/objects/document-archive
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” |