Endpoint Summary
This table provides quick access to the document and document type query services under the Assets section. Detailed request and response fields are included in the relevant sections.
| No | Service | Endpoint |
|---|---|---|
| 1 | Document Query | POST /api/v1/query/documents |
| 2 | Document Type Query | POST /api/v1/query/documenttypes |
General Technical Information
For the Assets query endpoints on this page, authentication information is sent in the request body.
ClientId and AppKey fields are required.
This section is prepared to query document and document type records managed in PIM. The endpoints do not create or update data; they list existing asset records.
Document records can be associated with products, variants, or different entity types.
This relationship is interpreted through the RelatedDataEntityType and RelatedDataEntityId fields.
The areas where documents are stored can be tracked through the VaultId and FolderId fields.
This structure enables documents to be positioned within the file system or document explorer.
Records are returned in the Result field, while the total record count is returned in the
TotalCount field.
Document refers to a digital file record that can be associated with a product, variant, or other catalog assets in PIM. Assets such as images, PDFs, Excel files, technical documents, or user manuals can be managed through this structure.
Document type is reference data that defines the format or selection type of the document. Whether the file is an image or a document, and the format in which it is stored, can be interpreted through this structure.
1. Document Query —
POST /api/v1/query/documents
This endpoint is used to retrieve files from the Document Management screens in the PIM UI, including Document Explorer and product/variant media management, through the API.
GetDocumentsis used to query document assets registered in PIM.DocumentIds,FolderIds, andVaultIdsparameters can be used to filter documents by identity and location.EntityTypesandEntityIdsparameters enable querying based on the product, variant, or related entity records to which the documents are linked.TypeIdsparameter can be used to retrieve only records belonging to specific document types.DocumentKey,DocumentPath, andRelativeDocumentPathfields can be used to interpret the file location on the storage side.ValidFromandValidThrufields should be checked in scenarios where the document has a validity period.
Usage Notes for Document Data
- Files displayed in product or variant media management can be associated with document records.
- The catalog asset to which the document is linked can be tracked through the
RelatedDataEntityTypeandRelatedDataEntityIdfields. - The file format and how the file is classified should be evaluated together with the
DocumentTypeobject. - Tag and custom field information can be used in document search, filtering, and classification processes.
Endpoint-Specific Query Parameters
| API Parameter | Type | PIM UI Equivalent / Meaning | Description |
|---|---|---|---|
TypeIds |
array (integer) |
Document Type ID List | Filters by specific document types, for example only PDFs. |
EntityTypes |
array (string) |
Related Entity Type | Entity type to which the document is related, for example Product or Variant. |
EntityIds |
array (integer) |
Related Entity ID List | ID of the entity to which the document is linked. |
DocumentIds |
array (guid) |
Document ID List | Filters specific documents by ID. |
FolderIds |
array (guid) |
Folder ID List | Filters documents in specific folders. |
VaultIds |
array (guid) |
Vault ID List | Filters documents in specific vaults. |
Codes |
array (string) |
Document Code Filter | Filters by document code. |
DocumentKeys |
array (string) |
Document Key Filter | Filters by document key. |
Tags |
array (object) |
Tag Filter | Filters by tags assigned to the document. |
API Response Parameters and UI Equivalents
Each DocumentResponse object in the Result array contains the following fields:
| API Response Field | Type | PIM UI Equivalent / Field Name | Description |
|---|---|---|---|
DocumentId | guid | Document Unique ID | Unique file identity in the document management system. |
Name | string | File Name | File name displayed in the document explorer and product/variant media list. |
Description | string | Description | Description text of the document. |
SourceDocumentCode | string | Source Document Code | Document code in the original source system. |
DocumentKey | string | Document Key | Unique key in the storage area. |
DocumentPath | string | File Path | Full path of the file on the server. |
RelativeDocumentPath | string | Relative File Path | Relative path of the file. |
FileSize | decimal | File Size | File size information. |
TypeId | integer | Document Type ID | Reference ID of the document type. |
DocumentType | object | Document Type | Document type detail information, such as name and extension. |
VaultId | guid? | Vault ID | ID of the vault where the document is located. |
Vault | object | Vault Information | Vault detail information. |
FolderId | guid? | Folder ID | ID of the folder where the document is located. |
Folder | object | Folder Information | Folder detail information. |
RelatedDataEntityType | string | Related Entity Type | Entity type to which the document is linked. |
RelatedDataEntityId | integer | Related Entity ID | ID of the entity to which the document is linked. |
IssueDate | datetime? | Issue Date | Issue date of the document. |
ValidFrom | datetime? | Validity Start | Validity start date of the document. |
ValidThru | datetime? | Validity End | Validity end date of the document. |
Properties | array | Document Properties | Custom fields defined for the document. |
Tags | array | Document Tags | Tags assigned to the document. |
DocumentEntities | array | Related Entities | List of all entities to which the document is linked. |
Status | integer | Status | 1 = Active, -1 = Passive. |
Created | datetime | Creation Date | Date when the document was uploaded to the system. |
Updated | datetime? | Update Date | Last update date. |
Usage Guide in the UI
- Document Explorer: The document explorer screen in the UI is populated through this endpoint. The vault and folder structure is determined by
VaultIdandFolderId. - Product/Variant Media Relationship: You can learn which product or variant a document is linked to from the
RelatedDataEntityTypeandRelatedDataEntityIdfields.
2. Document Type Query —
POST /api/v1/query/documenttypes
This endpoint is used to retrieve document type definitions in the PIM UI, such as PDF, JPEG, and XLSX, through the API. It is used to list and filter file types in document management.
GetDocumentTypesis used to query document type records defined in the system.- Document type is used as reference data to standardize the format and selection type of the document.
TypeCodefield represents the file extension or format information.SelectionTypefield can determine whether the related type is evaluated as an image or a document.- This endpoint can be used to retrieve supported types in document upload and document filtering scenarios.
Usage Notes for Document Type
- In document lists, format icons and format labels can be interpreted through the
TypeCodefield. - Document type information can be used as a reference in controls such as file acceptance rules and media/document distinction.
- Active/passive status information should be considered when listing available document types.
Endpoint-Specific Query Parameters
This endpoint does not include any additional endpoint-specific filter parameter other than BaseQuery parameters.
(Only common parameters: ClientId, AppKey, PageIndex, PageSize, Sorting, Status, ThreadId)
API Response Parameters and UI Equivalents
Each DocumentType object in the Result array contains the following fields:
| API Response Field | Type | PIM UI Equivalent / Field Name | Description |
|---|---|---|---|
TypeId |
integer |
Type System ID | Unique ID of the document type. |
TypeCode |
string |
Format / File Extension | File type extension shown under the “Format” column in the document row in the UI, for example PDF, JPEG, or XLSX. |
Name |
string |
Type Name | Display name of the document type. |
SelectionType |
string |
Selection Type | Type information indicating whether the document is an image or a document. |
Status |
integer |
Status | 1 = Active, -1 = Passive. |
Created |
datetime |
Creation Date | Date when the type was added to the system. |
Updated |
datetime? |
Update Date | Last update date. |
Usage Guide in the UI
- File Format Icon: The file type shown in the format column in the document list in the UI, such as PDF or Excel, is read directly from the
TypeCodefield. - Document Upload: When uploading a new document, you can retrieve which file types the system supports from this endpoint.
Common Error Cases
The table below is prepared for the common error cases that may apply to the endpoints under the Assets section. The error message field is left blank so endpoint-specific returned messages can be added.
| HTTP Status | Status | Error Message |
|---|---|---|
400 | Bad Request | |
401 | Unauthorized | |
403 | Forbidden | |
404 | Not Found | |
422 | Unprocessable Entity | |
429 | Too Many Requests | |
500 | Internal Server Error |