diff --git a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml index f59f18611..34fa0963d 100644 --- a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml +++ b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml @@ -6,14 +6,14 @@ info: # Introduction The DocuMine API provides a comprehensive solution for managing resources such as dossiers and their associated files. - Users can also retrieve components of files that have been processed and extracted by the system. + Users can also retrieve components that the system has extracted from the processed files. # Authorization - All endpoints are secured using OAuth2, with the "authorizationCode" being the general supported authorization flow. - Obtain a JWT token for authentication and send it in the 'Authorization' header with the format `Bearer {JWT_TOKEN}`. + All endpoints are secured using OAuth2; the supported authorization flow is "authorizationCode". + Please obtain a JWT token for authentication and send it in the 'Authorization' header using the `Bearer {JWT_TOKEN}` format. - Please also note that the `authorizationUrl` and `tokenUrl` in this specification contain `{workspaceId}` placeholders that + Please note that the `authorizationUrl` and `tokenUrl` in this specification contain `{workspaceId}` placeholders that must be replaced by your respective DocuMine workspace identifier. **Example Headers:** @@ -43,7 +43,7 @@ tags: - name: 3. Files description: Operations for managing files within a dossier. - name: 4. Components - description: Operations related to components of a file within a dossier. + description: Operations related to components extracted from a file within a dossier. - name: 5. Downloads description: Operations related to download packages. - name: 6. Users @@ -58,13 +58,13 @@ paths: - 1. Dossier Templates summary: Retrieve a list of all available dossier templates. description: | - This endpoint provides a list of all dossier templates stored in the system. + Use this endpoint to retrieve a list of all dossier templates stored in the system. - It returns an object containing an array of dossier template objects under the key `dossierTemplates`. - Each template object contains an identifier, a name, a dossier template status, and other fields with + It returns an object containing an array of dossier template objects under the `dossierTemplates` key. + Each template object includes an identifier, a name, a dossier template status, and other fields providing further details about the template. - Use this endpoint to fetch all templates before performing actions on specific ones. + Use this endpoint to retrieve all templates before performing actions on specific ones. responses: "200": content: @@ -92,8 +92,8 @@ paths: - 1. Dossier Templates summary: Retrieve a specific dossier template by its identifier. description: | - Utilize this endpoint to retrieve comprehensive details about a designated dossier template. The response encompasses - various attributes such as the dossier template's identifier, name, status, among other pertinent details. + Use this endpoint to retrieve comprehensive details about a specific dossier template. The response includes + various attributes such as the dossier template's identifier, name, status, among other relevant details. parameters: - $ref: '#/components/parameters/dossierTemplateId' responses: @@ -123,15 +123,15 @@ paths: - 1. Dossier Templates summary: Download the entity rules of a specific dossier template. description: | - Utilize this endpoint to download the entity rules of a designated dossier template. The file is named 'entity-rules.drl' - and contains the set of rules to annotate the entities in an analyzed file. The content of this file is in the Drools Rule Language - (DRL) format. Please find more details about the DRL in the + Use this endpoint to download the entity rules of a specific dossier template. The file, named 'entity-rules.drl', + contains the set of rules governing the entity annotation in analyzed files. The content of the file is in the Drools Rule Language + (DRL) format. For further details on the DRL, please see [Drools Language Reference](https://docs.drools.org/8.44.0.Final/drools-docs/drools/language-reference/index.html). parameters: - $ref: '#/components/parameters/dossierTemplateId' responses: "200": - headers: + headers: Content-Disposition: schema: type: string @@ -158,13 +158,13 @@ paths: operationId: uploadEntityRules tags: - 1. Dossier Templates - summary: Upload or validate a entity rules file for a specific dossier template. + summary: Upload or validate an entity rules file for a specific dossier template. description: | - Utilize this endpoint to upload the entity rules to a designated dossier template. With the 'dryRun' parameter, - you have the possibility to just validate the rules file without actually saving it in the dossier template. + Use this endpoint to upload the entity rules to a specified dossier template. With the 'dryRun' parameter, + you can validate the rules file without actually saving it in the dossier template. - The uploaded rule file will be saved only if 'dryRun' is set to `false` and the response code is `200`. In this - case, the response object does not contain errors. + The uploaded rule file will be saved only if 'dryRun' is set to `false` and the response code is `200`, indicating + sucess with no errors in the response object. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dryRun' @@ -204,9 +204,9 @@ paths: - 1. Dossier Templates summary: Download the component rules of a specific dossier template. description: | - Utilize this endpoint to download the component rules of a designated dossier template. The file is named 'component-rules.drl' - and contains the set of rules to build components based on entities of an analyzed file. The content of this file is in the Drools Rule Language - (DRL) format. Please find more details about the DRL in the + Use this endpoint to download the component rules of a specified dossier template. The file, named 'component-rules.drl', + contains the set of rules governing the component construction based on entities that have been extracted from an analyzed file. + The content of the file is in the Drools Rule Language (DRL) format. For further details about the DRL, please see [Drools Language Reference](https://docs.drools.org/8.44.0.Final/drools-docs/drools/language-reference/index.html). parameters: - $ref: '#/components/parameters/dossierTemplateId' @@ -241,8 +241,8 @@ paths: - 1. Dossier Templates summary: Upload or validate a component rules file for a specific dossier template. description: | - Utilize this endpoint to upload the component rules to a designated dossier template. With the 'dryRun' parameter, - you have the possibility to just validate the rules file without actually saving it in the dossier template. + Use this endpoint to upload the component rules to a specified dossier template. With the 'dryRun' parameter, + you can validate the rules file without actually saving it in the dossier template. The uploaded rule file will be saved only if 'dryRun' is set to `false` and the response code is `200`. In this case, the response object does not contain errors. @@ -281,13 +281,13 @@ paths: /api/dossier-templates/{dossierTemplateId}/dossier-status-definitions: get: operationId: getDossierStatusDefinitions - summary: Returns the list of all existing dossier status definitions + summary: Returns the list of all existing dossier status definitions. tags: - 1. Dossier Templates description: | - Retrieves a collection of dossier status definitions associated with a specific dossier template. + Use this endpoint to retreive a collection of dossier status definitions associated with a specific dossier template. - This endpoint is useful for clients needing to display or set the status of a dossier associated + This endpoint is useful for clients who need to display or update the status of a dossier associated with a specific dossier template. #### Response @@ -319,18 +319,18 @@ paths: /api/dossier-templates/{dossierTemplateId}/dossier-attribute-definitions: get: operationId: getDossierAttributeDefinitions - summary: Returns the list of all existing dossier attribute definitions + summary: Returns the list of all existing dossier attribute definitions. tags: - 1. Dossier Templates description: | - Retrieves a collection of dossier attribute definitions associated with a specific dossier template. + Use this endpoint to retrieve a collection of dossier attribute definitions associated with a specific dossier template. - This endpoint is useful for clients needing to understand what attributes are expected or allowed + This endpoint is useful for clients who need to understand which expected or allowed for dossiers associated with a specific dossier template. #### Response - Each dossier attribute definition includes details such as attribute type, name, and other relevant + Each dossier attribute definition includes details such as the attribute type, name, and other relevant metadata. parameters: - $ref: '#/components/parameters/dossierTemplateId' @@ -357,14 +357,14 @@ paths: /api/dossier-templates/{dossierTemplateId}/file-attribute-definitions: get: operationId: getFileAttributeDefinitions - summary: Returns the list of all existing file attribute definitions + summary: Retrieve a list of all existing file attribute definitions. tags: - 1. Dossier Templates description: | Use this endpoint to retrieve a collection of file attribute definitions associated with a specific dossier template. Each file - attribute definition includes details such as attribute type, name, and other relevant metadata. This endpoint - is useful for clients needing to understand what attributes are expected or allowed for files associated with - a specific dossier template. + attribute definition includes details such as the attribute type, name, and other relevant metadata. This endpoint + is useful for clients who need to understand which attributes are expected or allowed for files associated with + a particular dossier template. parameters: - $ref: '#/components/parameters/dossierTemplateId' responses: @@ -392,12 +392,12 @@ paths: operationId: listAllMappings tags: - 1. Dossier Templates - summary: Returns a list of all existing component mappings in a dossier template + summary: Returns a list of all component mappings existing in a dossier template. description: | - Use this endpoint to retrieve a summary of all component mappings associated with a specific DossierTemplate. + Use this endpoint to retrieve a list of all component mappings associated with a specific DossierTemplate. - The summary consists of the stored metadata of a component mapping file. - This endpoint is useful for clients to understand the available mappings under a particular DossierTemplate. + The list includes metadata of the stored component mapping file. + This endpoint is useful for clients who want to understand the available mappings associated with a particular DossierTemplate. parameters: - $ref: '#/components/parameters/dossierTemplateId' responses: @@ -407,7 +407,7 @@ paths: schema: $ref: '#/components/schemas/ComponentMappingList' description: | - Successfully returned the component mapping summary for the specified dossier template. + Successfully returned the component mapping list for the specified dossier template. "400": $ref: '#/components/responses/400' "401": @@ -429,17 +429,17 @@ paths: #### File Requirements - **Format:** The file must be in CSV (comma-separated values) format. - **Header Row:** The first row should contain the column labels. - - **Data Consistency:** All rows must have the same number of columns to ensure rectangular data structure. + - **Data Consistency:** All rows must have the same number of columns to ensure a rectangular data structure. #### Sorting and Performance - **Sorting:** Rows are automatically sorted by the values in each column, from left to right, to enhance lookup speed. - - **Optimization Tip:** Place keys to be queried in the first columns and the results to be mapped in the last column for best performance. + - **Optimization Tip:** For optimal performance, place the keys to be queried in the first columns and the results to be mapped in the last column. #### Customization Options - - Users can specify the delimiter and encoding used in the CSV file. + - Users can define the delimiter and encoding used in the CSV file. #### Usage - - The component mapping file can be utilized in component rules to relate components to existing master data. + - The component mapping file can be referenced in the component rules to relate components to existing master data. #### Example @@ -467,7 +467,7 @@ paths: schema: $ref: '#/components/schemas/ComponentMapping' description: | - Component mapping uploaded successfully and returned the component mapping metadata. + Component mapping uploaded successfully and the component mapping metadata has been returned. "400": $ref: '#/components/responses/400' "401": @@ -486,11 +486,11 @@ paths: operationId: downloadMappingFile tags: - 1. Dossier Templates - summary: Download a specific component mapping file of a specific dossier template. + summary: Download a particular component mapping file of a dossier template. description: | - Use this endpoint to download a specific component mapping file of a designated DossierTemplate. + Use this endpoint to download a particular component mapping file associated with a specific DossierTemplate. - - The file retains its original name and encoding as when it was uploaded. + - The file retains the same name and encoding as when it was uploaded. - The sorting of the file may have changed to enable faster lookups. parameters: - $ref: '#/components/parameters/dossierTemplateId' @@ -524,7 +524,7 @@ paths: operationId: updateMapping summary: Update an existing component mapping of a DossierTemplate. description: | - Use this endpoint to update an existing component mapping of a specific dossier template. + Use this endpoint to update an particular component mapping associated with a specific dossier template. #### File Requirements - **Format:** The file must be in CSV (comma-separated values) format. @@ -533,10 +533,10 @@ paths: #### Sorting and Performance - **Sorting:** Rows are automatically sorted by the values in each column, from left to right, to enhance lookup speed. - - **Optimization Tip:** Place keys to be queried in the first columns and the results to be mapped in the last column for best performance. + - **Optimization Tip:** For optimal performance, place the keys to be queried in the first columns and the results to be mapped in the last column. #### Customization Options - - Users can specify the delimiter and encoding used in the CSV file. + - Users can define the delimiter and encoding used in the CSV file. tags: - 1. Dossier Templates requestBody: @@ -574,9 +574,9 @@ paths: operationId: deleteMappingFile tags: - 1. Dossier Templates - summary: Delete a specific component mapping file of a specific dossier template. + summary: Delete a particular component mapping file of a dossier template. description: | - Use this endpoint to delete a specific component mapping file of a designated dossier template. + Use this endpoint to delete a particular component mapping file associated with a designated dossier template. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/componentMappingId' @@ -601,11 +601,11 @@ paths: operationId: createComponents tags: - Component Definitions - summary: Create new component definitions + summary: Create new component definitions. description: | - Create new component definitions for a given dossier template. The component will have a technical name which is automatically converted to snake case - that can't be updated after the creation. The rank is used to determine the order in which the components are displayed. The component's rank will - automatically be appended at the end based on the current number of components of this dossier template. + Use this endpoint to create new component definitions for a specific dossier template. The component will have a technical name that is automatically generated in snake case + and cannot be changed after creation. The rank determines the display order of the components. The component's rank will + automatically be appended at the end based on the current number of components associated with the given dossier template. parameters: - $ref: '#/components/parameters/dossierTemplateId' requestBody: @@ -641,10 +641,11 @@ paths: operationId: getComponentDefinitions tags: - Component Definitions - summary: Get all component definitions + summary: Retrieve all component definitions. description: | - Get all the component definitions in a given dossier template. `includeSoftDeleted` is false by default and will not return soft deleted components. If set to true, - this endpoint will also return components that have been soft deleted. + Use this endpoint to retrieve all the component definitions associated with a given dossier template. + - `includeSoftDeleted` is false by default and will not return soft deleted components. + - If set to `true`, this endpoint will also return components that have been soft deleted. parameters: - $ref: '#/components/parameters/dossierTemplateId' - name: includeSoftDeleted @@ -654,8 +655,9 @@ paths: default: false type: boolean description: | - A toggle to include or exclude soft-deleted components: If `false` (default), soft-deleted components - are not included. If `true`, they are included. + A toggle to include or exclude soft-deleted components: + - If `false` (default), soft-deleted components are not included. + - If `true`, they are included. responses: "200": description: OK @@ -681,10 +683,10 @@ paths: operationId: updateComponents tags: - Component Definitions - summary: Update existing component definitions + summary: Update existing component definitions. description: | - Update specific existing component definitions. The rank and technical name cannot be updated via this endpoint. The technical name cannot be updated - at all after creation. To update the rank, use the [reorder endpoint](#/paths/~1dossier-templates~1{dossierTemplateId}~1component-definitions~1reorder/post). + Use this endpoint to update existing component definitions. Please note that the rank and technical name cannot be modified through this endpoint. + The technical name cannot be changed at all after creation. To update the rank, use the [reorder endpoint](#/paths/~1dossier-templates~1{dossierTemplateId}~1component-definitions~1reorder/post). parameters: - $ref: '#/components/parameters/dossierTemplateId' requestBody: @@ -720,10 +722,10 @@ paths: operationId: deleteComponents tags: - Component Definitions - summary: Soft delete component definitions + summary: Soft delete component definitions. description: | - Soft delete existing component definitions by their IDs. Soft deletion is done by setting the `softDeletedTime` value to the current time of the request. If a component - does not have `softDeletedTime` set, it means the component is not soft deleted. + Use this endopint to soft delete existing component definitions by their IDs. This is achieved by setting the `softDeletedTime` value to the time of the request. If `softDeletedTime` is not set + for a component, the component is not soft deleted. parameters: - $ref: '#/components/parameters/dossierTemplateId' - name: componentIds @@ -733,7 +735,7 @@ paths: type: array items: type: string - description: The IDs of the component definitions to soft delete + description: The IDs of the component definitions intended for soft deletion responses: "204": description: No Content @@ -754,8 +756,8 @@ paths: operationId: reorderComponents tags: - Component Definitions - summary: Reorder component definitions - description: Reorder the component definitions based on the provided list. Their ranks will be updated based on the order provided in the request, starting from rank 1. + summary: Reorder component definitions. + description: Use this endopint to reorder the component definitions based on the provided list. Their ranks will be updated based on the order provided in the request, starting from rank 1. parameters: - $ref: '#/components/parameters/dossierTemplateId' - name: componentIds @@ -792,8 +794,8 @@ paths: operationId: getComponent tags: - Component Definitions - summary: Get specific component by ID - description: Get details about a specific component based on its ID for a given dossier template. + summary: Retrieve specific component by ID. + description: Use this endpoint to retrieve details about a specific component based on its ID within a given dossier template. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/componentId' @@ -823,9 +825,9 @@ paths: operationId: restoreComponents tags: - Component Definitions - summary: Restore soft deleted components by ID + summary: Restore soft deleted components by ID. description: | - Restore a previously soft-deleted component. The restored component will be placed at the end of the rank order. + Use this endpoint to restore a previously soft-deleted component. The restored component will be placed at the end of the rank order. For example, if there are 5 components ranked 1, 2, 3, 4, and 5, and the third component is soft-deleted, the ranks will be updated to 1, 2, 4, and 5. If the soft-deleted component is then restored, it will be appended to the end, resulting in ranks 1, 2, 4, 5, and 6. parameters: @@ -837,7 +839,7 @@ paths: type: array items: type: string - description: The IDs of the component definitions to restore. + description: The IDs of the component definitions to be restored responses: "200": description: OK @@ -862,13 +864,13 @@ paths: /api/dossier-templates/{dossierTemplateId}/report-templates: get: operationId: getReportTemplates - summary: Returns the list of all available report templates + summary: Returns the list of all available report templates. tags: - 1. Dossier Templates description: | Use this endpoint to retrieve a collection of report templates associated with a specific dossier template. Each report - template includes details such as the report's name, whether the report is per file or for multiple files, and if the UI - should pre-select it in a download dialog. + template includes details such as the report's name, whether it is a single-file or multi-file template, and whether it + is pre-selected in a download dialog in the UI. parameters: - $ref: '#/components/parameters/dossierTemplateId' responses: @@ -878,7 +880,7 @@ paths: schema: $ref: '#/components/schemas/ReportTemplateList' description: | - Successfully returned the file attribute definitions for the specified dossier template. + Successfully returned the report templates available for the specified dossier template. "400": $ref: '#/components/responses/400' "401": @@ -900,12 +902,12 @@ paths: description: | By default, this endpoint provides a list of all *active* dossiers that are based on a specific dossier template. - It returns an object containing an array of dossier objects under the key `dossiers`. Each dossier object contains - an identifier, a name, a description, an owner, and other fields with further details about the dossier. + It returns an object containing an array of dossier objects under the `dossiers` key. Each dossier object includes + an identifier, a name, a description, an owner, and other fields providing further details about the dossier. - Use this endpoint to fetch the required dossiers before performing actions on specific ones. Use the query parameters - to modify the response. E.g., set the `includeArchivedDossiers` parameter to `true` so that the response also contains - *archived* dossiers. + Use this endpoint to retrieve the required dossiers before performing actions on specific dossiers. Use the query parameters + to modify the response. E.g., set the `includeArchivedDossiers` parameter to `true` to include *archived* dossiers + in the response. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/includeActiveDossiers' @@ -918,11 +920,10 @@ paths: schema: $ref: '#/components/schemas/DossierList' description: | - Successfully retrieved the dossiers that are based on the requested dossier template. + Successfully retrieved the dossiers that are based on the specified dossier template. - The response could be an empty - list if there are no *active* dossiers based on it. If query parameters have been set, an empty list will be returned if - no dossier matches the respective combination. + The response could be an empty list if there are no *active* dossiers based on the specified dossier template. + If query parameters have been set, an empty list will be returned if no dossier matches the respective paramter(s). "400": $ref: '#/components/responses/400' "401": @@ -941,11 +942,11 @@ paths: - 2. Dossiers summary: Creates or updates a dossier for a specific dossier template. description: | - This endpoint is meant to create a new dossier or to update an existing one. + Use this endpoint to create a new dossier or update an existing dossier. To create a new dossier, do not set the identifier of the dossier object provided in the request body. - To update an existing dossier, the set identifier needs to be valid. + To update an existing dossier, ensure that the provided identifier is valid. parameters: - $ref: '#/components/parameters/dossierTemplateId' requestBody: @@ -988,10 +989,10 @@ paths: operationId: deleteDossier tags: - 2. Dossiers - summary: Deletes a specific dossier by its identifier. + summary: Delete a specific dossier by its identifier. description: | - Removes a dossier either in a recoverable manner (soft-delete) or permanently. By default, a soft-deleted dossier - remains recoverable for a retention period determined by application settings. The default retention period is + Use this endpoint to remove a dossier, either in a recoverable manner (soft-delete) or permanently. By default, a soft-deleted dossier + remains recoverable for a retention period specified in the application settings. The default retention period is 96 hours (4 days) but may vary based on configuration. parameters: - $ref: '#/components/parameters/dossierTemplateId' @@ -1000,7 +1001,7 @@ paths: responses: "204": description: | - Dossier deletion successful. Note that the absence of the dossier with the given `dossierId` is confirmed, + Dossier deletion successful. Please note: The absence of the dossier with the given `dossierId` is confirmed, regardless of whether it was pre-existing, already removed, or never present. "400": $ref: '#/components/responses/400' @@ -1020,11 +1021,11 @@ paths: - 2. Dossiers summary: Retrieve a specific dossier by its identifier. description: | - Utilize this endpoint to retrieve comprehensive details about a designated dossier. The response encompasses various - attributes such as the dossier's unique ID, name, description, associated owner, among other pertinent details. + Use this endpoint to retrieve comprehensive details about a specified dossier. The response includes various + attributes such as the dossier's unique ID, name, description, associated owner, and other relevant details. - If the dossier has been soft-deleted but not yet permanently deleted, the `includeSoftDeleted` parameter can be utilized - to get it. Without this, a soft-deleted dossier would return a `404 Dossier not found` error. + If the dossier has been soft-deleted but not yet permanently deleted, use `includeSoftDeleted` to retrieve it. + Attempting to access a soft-deleted dossier without this parameter would return a `404 Dossier not found` error. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1056,10 +1057,10 @@ paths: - 2. Dossiers summary: Update or set attributes for a specific dossier. description: | - Use this endpoint to update or set dossier attributes for a given dossier. - Ensure you provide the necessary dossier attributes within the request body. + Use this endpoint to update or set dossier attributes for a specific dossier. + Make sure to include all required dossier attributes in the request body - Use this route to maintain or enhance dossier metadata and properties. + Use this route to maintain or improve dossier metadata and properties. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1092,7 +1093,7 @@ paths: - 2. Dossiers summary: Initiate the creation of a download package for all files of a dossier. description: | - This endpoint allows you to define the content and initiate the creation of a + Use this endpoint to define the content and initiate the creation of a download package for all files within a dossier. #### Request @@ -1103,7 +1104,7 @@ paths: #### Response Includes an identifier for the download. Use this identifier to query the status - of the download package preparation and download the file once it is available. + of the download package preparation and download the package once it is available. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1138,13 +1139,13 @@ paths: operationId: getDossierStatus tags: - 3. Files - summary: Retrieves the status of the files of a specific dossier. + summary: Retrieve the status of the files of a specific dossier. description: | - This endpoint provides status information for each file within a designated dossier. + Use this endpoint to obtain status information for each file within a specified dossier. - The file status encompasses attributes such as identifier, file name, number of pages, file size, - processing and workflow status, among other pertinent details. By default, only active files - are fetched. However, various parameters can be combined to adjust the scope of the response. + The file status includes attributes such as the identifier, file name, number of pages, file size, + processing and workflow status, among other relevant details. By default, only the status of active files + is fetched. However, the scope of the response can be adjusted by combining various query parameters. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1161,7 +1162,7 @@ paths: Successfully retrieved file status information. The response could be an empty list if the dossier contains no *active* files. If query parameters - have been set, an empty list will be returned if no file matches the respective combination. + have been set, an empty list will be returned if no file matches the respective parameter combination. "400": $ref: '#/components/responses/400' "401": @@ -1188,18 +1189,18 @@ paths: Supported file formats include PDF documents, Microsoft Office documents (if supported by your license), CSV files, and ZIP archives. - Notably, Microsoft office files (file extensions `docx`, `xlsx`, or `pptx`) are automatically converted into PDF format - upon upload. Be aware that due to potential font discrepancies, the resulting PDF may slightly differ in appearance from + Microsoft office files (file extensions `docx`, `xlsx`, or `pptx`) are automatically converted into PDF format + upon upload. Please note that due to potential font discrepancies, the resulting PDF may slightly differ in appearance from the original. Nevertheless, our system ensures maximum fidelity to the original content. - CSV files offer support for bulk importing of file attributes. If the dossier is set up to map specific CSV fields to - file attributes and the uploaded CSV aligns with this mapping, the system will process the CSV accordingly. Mismatched - CSVs will be disregarded. For successfully processed CSV files, the response contains information about the file attributes - and the annotated files. + CSV files offer support for bulk importing of file attributes. If the dossier is configured to map certain CSV fields to + file attributes, and the uploaded CSV aligns with this mapping, the system will process the CSV accordingly. + However, if the CSV fields do not match the expected format, the file will be ignored. For CSV files that are processed + successfully, the response will include details about the file attributes and the files that were annotated. - ZIP archives offer support to upload multiple files at once. In case of an upload of a ZIP archive, the system returns a - list of unique identifiers of the contained files. The archive can even contain a mix of files like some PDF files and - a CSV file that will annotate some file attributes. + ZIP archives facilitate the bulk upload of multiple files. When you upload a ZIP archive, the system returns a list of + the unique identifiers of all contained files. The archive can even contain a mix of file types, including PDF files for analysis + and a CSV for adding file attributes. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1217,9 +1218,9 @@ paths: schema: $ref: '#/components/schemas/FileUploadResult' description: | - Successfully uploaded the file. Returns an object with the unique identifier of the uploaded file, a list of unique - identifiers in case of an uploaded ZIP archive, or some annotation information in case of a successfully processing - of an uploaded CSV file. + Successfully uploaded the file. If a single file was uploaded, the response includes the unique identifier of the uploaded file. + If a ZIP archive was uploaded, the response provides a list of unique identifiers for all files within the archive. + In the case of a successfully processed CSV file, the response contains annotation information related to the file attributes. "400": $ref: '#/components/responses/400' "401": @@ -1237,10 +1238,10 @@ paths: operationId: deleteFile tags: - 3. Files - summary: Deletes a specific file associated with a dossier and its template. + summary: Delete a specific file associated with a dossier and its template. description: | - Use this endpoint to remove of a file linked to a specific dossier under a dossier template. By default, the - file undergoes a soft-delete, meaning it can be restored within the retention period determined by application settings. + Use this endpoint to remove of a file linked to a specific dossier associated with a specific dossier template. By default, the + file is soft-deleted, allowing for restoration within the retention period defined in the application settings. The default retention period is 96 hours (4 days) but may vary based on configuration. Use the `deletePermanently` query parameter to opt for a permanent deletion, preventing any future restoration. parameters: @@ -1251,7 +1252,7 @@ paths: responses: "204": description: | - File deletion successful. This confirms the absence of the specified file, irrespective of its previous existence. + File deletion successful. This confirms the absence of the specified file, regardless of whether it existed previously. "400": $ref: '#/components/responses/400' "401": @@ -1268,11 +1269,11 @@ paths: operationId: getFileStatus tags: - 3. Files - summary: Retrieves the status of a particular file. + summary: Retrieve the status of a particular file. description: | - This endpoint is designed to fetch the status of a specific file associated to a dossier based on a dossier template. If - the file has been soft-deleted but not yet permanently deleted, the `includeSoftDeleted` parameter can be utilized to get - the status of such files. Without this, a soft-deleted file would return a `404 File not found` error. + Use this endpoint to retrieve the status of a specific file linked to a specific dossier associated with a specific dossier template. + If the file has been soft-deleted but not yet permanently deleted, you can use the `includeSoftDeleted` parameter to retrieve the status + of the file. The soft-deleted file will otherwise return a `404 File not found` error. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1305,18 +1306,18 @@ paths: - 3. Files summary: Initiate the creation of a download package for a single file of a dossier. description: | - This endpoint allows you to define the content and initiate the creation of a + Use this endpoint to define the content and initiate the creation of a download package for a files of a dossier. #### Request - * Specify the files and reports to be included in the download package. + * Specify the file and reports to be included in the download package. * Start the process of creating the download package. #### Response Includes an identifier for the download. Use this identifier to query the status - of the download package preparation and download the file once it is available. + of the download package preparation and download the package once it is available. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1357,8 +1358,8 @@ paths: This endpoint allows for the bulk deletion of specified files associated with a certain dossier. It provides the flexibility to perform either a soft-delete (by default) or a permanent deletion. A soft-deleted - file remains restorable within the retention period set by the application (96h by default). In contrast, permanently - deleted files are irrevocably removed and cannot be restored. + file remains restorable within the retention period defined in the application settings (96h by default). Permanently + deleted files, however, are irrevocably removed and cannot be restored. Use this route to manage large file deletions efficiently. parameters: @@ -1394,7 +1395,7 @@ paths: - 3. Files summary: Initiate the creation of a download package for specific files within a dossier. description: | - This endpoint allows you to define the content and initiate the creation of a + Use this endpoint to define the content and initiate the creation of a download package for specific files of a dossier. #### Request @@ -1405,7 +1406,7 @@ paths: #### Response Includes an identifier for the download. Use this identifier to query the status - of the download package preparation and download the file once it is available. + of the download package preparation and download the package once it is available. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1442,10 +1443,10 @@ paths: - 3. Files summary: Update or set attributes for a specific file. description: | - Use this endpoint to update or setting of specific file attributes for a given file within a dossier. - Ensure you provide the necessary file attributes within the request body. + Use this endpoint to update or set specific file attributes for a given file within a dossier. + Make sure you include the required file attributes in the request body. - Use this route to maintain or enhance file metadata and properties. + Use this route to maintain or improve file metadata and properties for a specific file. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1477,11 +1478,12 @@ paths: operationId: getComponents tags: - 4. Components - summary: Fetch the components associated with a specific file. + summary: Retrieve the components extracted from a specific file. description: | - This endpoint retrieves the derived and extracted components from a given file within a dossier. Components represent - various aspects, metadata or content of the file. Entity and component rules define these components based on the file's - content. They can give a *structured view* on a document's text. + Use this endpoint to retrieve the components derived and extracted from a given file within a dossier. Components represent + various aspects, metadata, or pieces of information extracted from the file. The extraction of these components is governed + by the entity and component rules based on the content of the file. Components can provide a *structured view* of the + unstructred text of the document. To include detailed component information, set the `includeDetails` query parameter to `true`. parameters: @@ -1519,9 +1521,10 @@ paths: - 4. Components summary: Returns the FileComponents of all files in a dossier description: | - This endpoint fetches components for all files associated with a specific dossier. Like individual file components, - these represent various aspects, metadata or content of the files. Entity and component rules define these components based on the file's - content. They can give a *structured view* on a document's text. + Use this endpoints to retrieve the components of all files associated with a specific dossier. As is the case with + the components of an individual file, these components represent various types of information, such as metadata or pieces of information + extracted from the file's content. The component extraction is governed by entity and component rules based on the content of the file. + Components can provide a *structured view* of the unstructured text of the document. To include detailed component information, set the `includeDetails` query parameter to `true`. parameters: @@ -1538,7 +1541,7 @@ paths: schema: $ref: '#/components/schemas/FileComponentsList' description: | - Successfully fetched components for all files in the dossier. + Successfully retrieved components for all files in the dossier. "400": $ref: '#/components/responses/400' "401": @@ -1556,14 +1559,14 @@ paths: operationId: getDownloadStatusList tags: - 5. Downloads - summary: Get the list of downloads for the current user + summary: Retrieve the list of downloads for the current user. description: | - Use this endpoint to retrieve the list of downloads for the current user. + Use this endpoint to retrieve the list of downloads associated with the current user. The response contains the status of each download. A download may be queued, generating, finished or failed. When it is finished, the - download package may be obtained using the download endpoint + download package may be obtained using the download endpoint. responses: "200": content: @@ -1586,11 +1589,11 @@ paths: operationId: getDownloadStatus tags: - 5. Downloads - summary: Get the status for a specific download of the current user + summary: Retrieve the status of a specific download of the current user. description: | Use this endpoint to retrieve the status for a specific download. In addition to other information, the status indicates whether the download is still being prepared, is already - available, or whether an error occurred when the download package was created. + available, or whether an error occurred during the download package generation. parameters: - $ref: '#/components/parameters/downloadId' responses: @@ -1616,7 +1619,7 @@ paths: operationId: deleteDownload tags: - 5. Downloads - summary: Deletes a specific download. + summary: Delete a specific download. description: | Use this endpoint to remove a download. parameters: @@ -1624,7 +1627,7 @@ paths: responses: "204": description: | - Download deletion successful. This confirms the absence of the specified download, irrespective of its previous existence. + Download deletion successful. This confirms the absence of the specified download, regardless of whether it existed previously. "400": $ref: '#/components/responses/400' "401": @@ -1678,12 +1681,12 @@ paths: operationId: getUsers tags: - 6. Users - summary: Get a list of users + summary: Retrieve list of users. description: | Use this endpoint to retrieve a list of known users. - With the `username` parameter you can filter for a specific user name. If the parameter is - used, the returned list either contains a single matching entry or is empty. + You can filter the list for a specific user name using the `username` parameter. If the parameter is + provided, the returned list will either contain a single matching entry or be empty. parameters: - $ref: '#/components/parameters/username' responses: @@ -1739,7 +1742,8 @@ paths: - 4. Components summary: Add the component overrides associated with a specific file. description: | - This endpoint allows the user to add one or more overrides for a specific component of a dossier file. The component override data is provided in the request body. + Use this endpoint to add one or more overrides for a specific component of a dossier file. + Provide the component override data in the request body. Use this route to add overrides to the specified component. parameters: @@ -1770,8 +1774,8 @@ paths: - 4. Components summary: Returns all overrides from components associated with a specific file. description: | - This endpoint retrieves all the overrides for components within a dossier file. - The response includes a list of all component overrides associated with the specified file. + Use this endpoint to retrieve all the overrides for components of a dossier file. + The response will include a list of all component overrides associated with the specified file. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1800,9 +1804,9 @@ paths: operationId: revertOverrides tags: - 4. Components - summary: Reverts the component overrides associated with a specific file. + summary: Revert the component overrides associated with a specific file. description: | - Reverts all overrides for the specified components associated with a specific file. + Use this endpoint to revert all overrides for the specified components of a specific file. Use this route to revert all overrides specified by the component names. parameters: @@ -1834,9 +1838,9 @@ paths: - 7. License summary: Generate and retrieve a license usage report. description: | - This endpoint enables users to create and fetch a report detailing the active usage of licenses. The report contains - valuable insights and metrics that can aid in monitoring and managing license consumption. Ensure your request body - contains the necessary parameters for generating this report. + Use this endpoint to create and fetch a report detailing the active usage of licenses. The report provides + valuable insights and metrics that can aid in monitoring and managing license consumption. Make sure to include + all necessary parameters to ensure the generated report meets your requirements. requestBody: content: application/json: @@ -1884,7 +1888,7 @@ components: $ref: '#/components/schemas/ErrorMessage' description: | Unauthorized access. You must provide valid authentication credentials to access this - resource. This error can happen if the access token was revoked or has expired. + resource. This error may occur if your access token has been revoked or expired. "403": content: 'application/json': @@ -1919,20 +1923,20 @@ components: schema: $ref: '#/components/schemas/ErrorMessage' description: | - Dossier not found. This happens if the dossier template or the dossier is deleted or did never exist. + Dossier not found. This happens if the dossier template or the dossier has been deleted or never existed. - Some endpoints support a `includeSoftDeleted` parameter: If this is set to `true`, this response is returned - for a previously existing dossier only if it is actually deleted permanently. + Some endpoints support the `includeSoftDeleted` parameter: If set to `true`, + the response is only returned if a previously existing dossier was permanently deleted. "404-file": content: 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | - File not found. This indicates that the dossier, dossier template, or file is deleted or did never exist. + File not found. This indicates that the dossier, dossier template, or file has been deleted or never existed. - Some endpoints support a `includeSoftDeleted` parameter: If this is set to `true`, this response is returned - only if the file is deleted permanently. + Some endpoints support the `includeSoftDeleted` parameter: If set to `true`, the response is returned only if the file + has been permanently deleted. "404-download": content: 'application/json': @@ -1953,7 +1957,7 @@ components: schema: $ref: '#/components/schemas/ErrorMessage' description: | - Name conflict: The provided name is already in use by another dossier. It needs to be unique in the scope of your workspace. + Name conflict: The provided name is already in use by another dossier. The name must be unique within your workspace. 422-rules: content: 'application/json': @@ -2001,7 +2005,7 @@ components: type: string style: simple explode: false - description: The identifier of a component definition. + description: The identifier of a component definition dryRun: name: dryRun in: query @@ -2012,8 +2016,8 @@ components: style: form explode: true description: | - A toggle to activate the dry-run mode: If set to `false` (default), the request will update the system. - If set to `true`, the request will just be evaluated without actual changes in the system. + A toggle to activate the dry-run mode: When set to `false` (default), the request will update the system. + When set to `true`, the request will just be evaluated without making actual changes in the system. encoding: name: encoding required: false @@ -2029,7 +2033,7 @@ components: - US-ASCII example: UTF-8 default: UTF-8 - description: "An identifier for the used encoding of the file. Only java's standard charsets are supported." + description: "An identifier for the file encoding used. Only java's standard charsets are supported." delimiter: name: delimiter required: false @@ -2040,7 +2044,7 @@ components: maxLength: 1 example: ',' default: ',' - description: "The delimiter used as a separator in a csv file." + description: "The delimiter used as the separator in the csv file." mappingName: name: name required: false @@ -2048,7 +2052,7 @@ components: schema: type: string example: "MasterDataMapping" - description: "The name with which the mapping should be associated with. If none is provided, the file name will be used." + description: "The name to associate with the mapping. If none is provided, the file name will be used." dossierId: name: dossierId in: path @@ -2077,9 +2081,9 @@ components: style: form explode: true description: | - A toggle to include or exclude active dossiers: If `true` (default), dossiers - that are neither archived nor soft-deleted are included. If `false`, they are - ignored. + A toggle to include or exclude active dossiers: + - `true` (default): The response will include active dossiers. + - `false`: Active dossiers are ignored and will not be part of the response. includeActiveFiles: name: includeActive in: query @@ -2090,9 +2094,9 @@ components: style: form explode: true description: | - A toggle to include or exclude active files: If set to `true` (default), files - that neither belong to an archived dossier nor have been soft-deleted are - included. If set to `false`, they are ignored. + A toggle to include or exclude active files: + - `true` (default): The response will include files from active dossiers. + - `false`: Active dossiers will are ignored and will not be part of the response. includeArchivedDossiers: name: includeArchived in: query @@ -2103,8 +2107,9 @@ components: style: form explode: true description: | - A toggle to include or exclude archived dossiers: If set to `true`, archived - dossiers are included. If set to `false` (default), they are ignored. + A toggle to include or exclude archived dossiers: + - `true`: The response will include archived dossiers. + - `false` (default): Archived dossiers are ignored and will not be part of the response. includeArchivedFiles: name: includeArchived in: query @@ -2116,8 +2121,8 @@ components: explode: true description: | A toggle to include or exclude archived files (i.e., files of archived dossiers): - If set to `true`, files of archived dossiers are included. If set to `false` - (default), they are ignored. + - `true`: The response will include files from archived dossiers. + - `false` (default): Files from archived dossiers are ignored and will not be part of the response. includeSoftDeletedDossiers: name: includeSoftDeleted in: query @@ -2143,10 +2148,10 @@ components: style: form explode: true description: | - A Toggle to return a soft-deleted dossier: - - `true`: The system returns the dossier regardless whether it has been soft-deleted or not. - - `false` (default): The system returns only non-deleted dossiers. It would return a `404 Dossier not found` error - if the requested dossier has been soft-deleted. + A toggle to return a soft-deleted dossier: + - `true`: The system returns the status of the file regardless of whether it has been soft-deleted. + - `false` (default): The system returns only undeleted dossiers. It returns a `404 Dossier not found` error + if the requested dossier has been soft-deleted. Soft-deleted means that the dossier has not been deleted permanently. includeSoftDeletedFiles: @@ -2163,7 +2168,7 @@ components: - `true`: The response will include soft-deleted files. - `false` (default): Soft-deleted files are ignored and will not be part of the response. - Soft-deleted means that the file or dossier of the file has not been deleted permanently. + Soft-deleted means that the file or dossier containing the file has not been deleted permanently. includeSoftDeletedFile: name: includeSoftDeleted in: query @@ -2174,12 +2179,12 @@ components: style: form explode: true description: | - A Toggle to return the status of soft-deleted files: - - `true`: The system returns the status of the file regardless whether it has been soft-deleted or not. - - `false` (default): The system returns only non-deleted files. It would return a `404 File not found` error - if the requested file has been soft-deleted. + A toggle to return the status of soft-deleted files: + - `true`: The system returns the status of the file regardless of whether it has been soft-deleted. + - `false` (default): The system returns only undeleted files. It returns a `404 File not found` error + if the requested file has been soft-deleted. - Soft-deleted means that the file or dossier of the file has not been deleted permanently. + "Soft-deleted" means that the file or dossier containing the file has not been deleted permanently. permanentlyDeleteDossier: name: deletePermanently in: query @@ -2190,11 +2195,12 @@ components: style: form explode: true description: | - A toggle to determine the deletion mode for a dossier: - - `true`: The dossier will be permanently deleted and can't be restored. - - `false` (default): Soft-delete, allowing restoration within the application-configured retention period. + A toggle to determine the deletion method for a dossier: + - `true`: The dossier will be permanently deleted and cannot be restored. + - `false` (default): Soft-deletes the dossier, allowing for restoration within the retention period configured on application level. - Using this parameter, you can also permanently delete a previously soft-deleted dossier during its retention period. + + You can also use this parameter to permanently delete a previously soft-deleted dossier during its retention period. > **Note:** Deleting a dossier also deletes all associated files. permanentlyDeleteFile: @@ -2207,12 +2213,12 @@ components: style: form explode: true description: | - Determines the deletion mode for a file. - - `true`: The file will be permanently deleted and can't be restored. - - `false` (default): Soft-delete, allowing restoration within the retention period, provided its parent dossier - hasn't been deleted. If the parent dossier has been deleted meanwhile, it needs to be restored first. + A toggle to determine the deletion method for a file: + - `true`: The file will be permanently deleted and cannot be restored. + - `false` (default): Soft-deletes the file, allowing restoration within the retention period, provided its parent dossier + has not been deleted. If the parent dossier has been deleted in the meantime, it must be restored first. - Using this parameter, you can also permanently delete a previously soft-deleted file during its retention period. + You can also use this parameter to permanently delete a previously soft-deleted file during its retention period. permanentlyDeleteFiles: name: deletePermanently in: query @@ -2223,12 +2229,12 @@ components: style: form explode: true description: | - Determines the deletion mode for a list of files: + Determines the deletion method for a list of files: - `true`: The files will be permanently deleted and can't be restored. - - `false` (default): Soft-delete, allowing restoration within the retention period, provided the files' parent dossier - hasn't been deleted. If the parent dossier has been deleted meanwhile, it needs to be restored first. + - `false` (default): Soft-deletes the listed files, allowing restoration within the retention period, provided the files' parent dossier + has not been deleted. If the parent dossier has been deleted in the meantime, it must be be restored first. - Using this parameter, you can also permanently delete a previously soft-deleted files during their retention period. + You can also use this parameter to permanently delete a previously soft-deleted files during their retention period. keepManualChanges: name: keepManualChanges in: query @@ -2239,10 +2245,10 @@ components: style: form explode: true description: | - A toggle to keep manual changes, i.e., to preserve manually added annotations or manipulations on existing ones when + A toggle to keep manual changes, i.e., to preserve manually added annotations or edits of auto-generated annotations when overwriting a file: - - `true`: The system keeps the manual changes on re-uploading (overwriting) the file. - - `false` (default): Manual changes get discarded on re-uploading the file. + - `true`: The system keeps the manual changes when the file is re-uploaded (overwritten). + - `false` (default): Manual changes are discarded on re-uploading (overwriting) the file. disableAutomaticAnalysis: name: disableAutomaticAnalysis in: query @@ -2267,9 +2273,9 @@ components: explode: true description: | A toggle to decide whether to include detailed component information in the response: - - `true`: The component object's field `componentDetails` stores detailed information about the *source* of its - respective value(s). - - `false` (default): The component object does not contain a field `componentDetails`. + - `true`: The component object's `componentDetails` field stores detailed information about the *source* of its + respective value(s). + - `false` (default): The component object does not contain a `componentDetails` field. downloadId: name: downloadId in: path @@ -2304,18 +2310,18 @@ components: EntityReference: type: object description: | - Represents a reference to an entity object discovered in a document. Together with the unique identifier - of the entity, the reference contains some basic details of the entity. + Represents a reference to an entity object detected in a document. In addition to the entity's unique identifier, + the reference contains basic details about the entity. properties: id: type: string description: | - The unique identifier for the entity. + The unique identifier of the entity. - > **Note:** In general, it is a valid UUID. Only if an entity spans over multiple pages, it is split on page breaks. Each - > part becomes an own entity object and the first one keeps the UUID while the following get an additional suffix. + > **Note:** In general, it is a valid UUID. Only if an entity spans over multiple pages, it is split at page breaks. Each + > part becomes a separate entity object, with the first part retaining the original UUID, and subsequent parts receiving a suffix. > - > Example: Even if `bcd22239-c3df-442f-a5a1-1664cba94dc6_2` is not a valid UUID it is still a valid identifier for an + > Example: Even if `bcd22239-c3df-442f-a5a1-1664cba94dc6_2` is not a valid UUID, it is still a valid identifier for an > entity object. entityRuleId: type: string @@ -2334,7 +2340,7 @@ components: page: 123 Component: type: object - description: Represents a component with its associated values. + description: Represents a component along with its associated values. properties: name: type: string @@ -2375,17 +2381,17 @@ components: page: 123 ComponentValue: type: object - description: Describes a value associated with a component, including its origin and related entities found in the document. + description: Describes a value associated with a component, providing information about its origin and related entities found in the document. properties: value: type: string description: The current value of the component. originalValue: type: string - description: The original value before any modifications. + description: The original value bprior to any modifications. componentRuleId: type: string - description: Identifier for the rule associated with this component value. + description: Identifier of the rule associated with this component value. valueDescription: type: string description: A brief description of the value. @@ -2414,14 +2420,14 @@ components: dossierTemplateId: format: uuid type: string - description: Identifier for the template associated with the dossier. + description: Identifier of the template associated with the dossier. dossierId: format: uuid type: string - description: Identifier for the dossier. + description: Identifier of the dossier. fileId: type: string - description: Identifier for the file. + description: Identifier of the file. componentOverrides: type: array description: List of files with their component details. @@ -2502,27 +2508,27 @@ components: dossierTemplateId: format: uuid type: string - description: Identifier for the template associated with the dossier. + description: Identifier of the template associated with the dossier. dossierId: format: uuid type: string - description: Identifier for the dossier. + description: Identifier of the dossier. fileId: type: string - description: Identifier for the file. + description: Identifier of the file. filename: type: string description: Name of the file. components: type: object - description: A map of component names to their list of values. + description: A map that associates the component names with their respective values. additionalProperties: items: type: string type: array componentDetails: type: object - description: A map of component names to their detailed representations. + description: A map that associates the component names with their detailed representations. additionalProperties: $ref: '#/components/schemas/Component' example: @@ -2582,7 +2588,7 @@ components: properties: files: type: array - description: List of files with their component details. + description: List of files along with their component details. items: $ref: '#/components/schemas/FileComponents' example: @@ -2703,27 +2709,25 @@ components: name: type: string description: | - User-defined name of the dossier status definition, capturing its essence. The name needs to be unique - for the dossier template. + User-defined name of the dossier status definition, that should be as descriptive as possible. The name needs to be unique + within the dossier template. example: "Done" description: type: string description: | - A text that can be added to provide further details about the status. E.g., what it is intended for or - the circumstances under which it can be used. - example: "Dossiers with this status should only contain approved files and indicate that the users have completed working on it." + A text that can be added to provide further details about the status, such as its purpose or when it should be used. + example: "Dossiers with this status should only contain approved files and indicate that the users have finished their work." rank: format: int32 type: integer description: | - A number that allows to define a custom display order. + A number that allows to set a custom display order of the defined statuses. default: "" example: 1 color: type: string description: | - A hexadecimal color code that can be set to assign a color to a - the `PREVIEW` file. + A hexadecimal color code that can be set to assign a color to the status. - Yellow is `#ffda05` - Green is `#5eb160` @@ -2743,19 +2747,20 @@ components: type: object description: | The `DossierAttributeDefinition` object contains the relevant information to define a dossier attribute. Dossier attributes - are used to manage additional meta-data of dossiers. + are used for managing additional metadata of dossiers. properties: id: type: string format: uuid description: | A unique identifier for the dossier attribute definition. This ID is automatically generated by - the system upon creation and is used for referencing the dossier attribute definition in API calls. + the system upon creation of the dossier attribute definition and is used for referencing the dossier attribute + definition in API calls. name: type: string description: | - User-defined name of the dossier attribute definition, capturing its essence. The name needs to be unique - for the dossier template. + User-defined name of the dossier attribute definition, that should be as descriptive as possible. The name needs to be unique + within the dossier template. type: type: string enum: @@ -2764,20 +2769,22 @@ components: - DATE - IMAGE description: | - Determines the type of the dossier attribute's value. Please note that currently the system - does not validate the values against this definition. This is just a hint for a user interface + Determines the type of the dossier attribute value. Please note that currently the system + does not validate the values against this definition; it primarily serves as guidance for the user interface that needs to handle invalid entries. Possible values for the type: - `TEXT`: The value is just a string, i.e., any sequence of characters. - - `NUMBER`: The value is a string expressing a number, with or without decimals. - - `DATE`: The value is a string expressing a date information. - - `IMAGE`: The value is a string representation of binary image, e.g. a BASE64 encoded image. + - `NUMBER`: The value is a string representing a number, with or without decimals. + - `DATE`: The value is a string representing date information. + - `IMAGE`: The value is a string representation of binary image, e.g. a BASE64-encoded image. reportingPlaceholder: type: string description: | The name of the placeholder of the dossier attribute that can be used in report templates. The placeholder follows a specific format convention: - `{{dossier.attribute.}}` while the name is transformed into 'PascalCase' and does not contain - whitespaces. The placeholder is unique in a dossier template. + - Format:`{{dossier.attribute.}}`. + - The name is transformed into 'PascalCase' and does not contain whitespaces. + + Each placeholder is unique within a dossier template. required: - name - type @@ -2789,20 +2796,21 @@ components: FileAttributeDefinition: type: object description: | - The `FileAttributeDefinition` object contains the relevant information to define a file attribute. File attributes - are used to manage additional meta-data of files. + The `FileAttributeDefinition` object contains the relevant information that is required for defining file attributes. + File attributes are used to manage file metadata. properties: id: type: string format: uuid description: | A unique identifier for the file attribute definition. This ID is automatically generated by - the system upon creation and is used for referencing the file attribute definition in API calls. + the system upon creation of the file attribute definition and is used for referencing the file attribute definition + in API calls. name: type: string description: | - User-defined name of the file attribute definition, capturing its essence. The name needs to be unique - for the dossier template. + User-defined name of the file attribute definition, that should be as descriptive as possible. The name needs to be unique + within the dossier template. type: type: string enum: @@ -3057,45 +3065,45 @@ components: type: object description: | The `Dossier` object captures all relevant information related to a specific dossier. A dossier is a collection - of documents, managed and analyzed based on settings and rules of the `DossierTemplate` it is derived from. + of documents, managed and analyzed based on settings and rules of the `DossierTemplate` it is based on. properties: id: type: string format: uuid description: | A unique identifier for the dossier. This ID is automatically generated by - the system upon creation and is used for referencing the dossier in API calls. + the system upon dossier creation and is used for referencing the dossier in API calls. name: type: string description: | - User-defined name of the dossier, capturing its essence. The name needs to be unique - for the entire workspace (i.e., tenant). + User-defined name of the dossier, that should be as descriptive as possible. The name needs to be unique + within the workspace (i.e., tenant). date: type: string format: date-time description: | - The date when the dossier was created. This is automatically set by the system upon the dossier's creation. + The dossier creation date. It is automatically set by the system upon dossier creation. dossierTemplateId: type: string format: uuid - description: The unique identifier for the template that governs the settings and rules for this dossier. + description: The unique identifier of the template containing the rules that are applied to the dossier. description: type: string - description: A detailed narrative explaining the purpose and contents of the dossier. + description: A detailed description outlining the purpose and contents of the dossier. ownerId: type: string format: uuid description: | The identifier of the user or entity responsible for the dossier. Typically, - this is the creator or main contact point for the dossier. Only users with "Manager" - privileges can create dossiers and become dossier owners. + this is the creator or main contact point for the dossier. Only users with the "Manager" + role can create dossiers and become dossier owners. memberIds: type: array items: type: string format: uuid uniqueItems: true - description: List of unique user identifiers associated with this dossier, such as contributors or viewers. + description: List of unique user identifiers associated with the dossier, such as contributors or viewers. approverIds: type: array items: @@ -3103,17 +3111,17 @@ components: format: uuid uniqueItems: true description: | - List of unique user identifiers with elevated permissions. Needed if using an approval workflow. + List of unique user identifiers with extended permissions. Needed if using a 2-step approval workflow. - > **Note:** The DocuMine application does not have an approval workflow. However, every member will be - > elevated to a privileged member to ensure full functionality. + > **Note:** DocuMine currently does not support the 2-step approval workflow. However, all members will be + > granted extended permissions to ensure full functionality. visibility: type: string enum: - PRIVATE - PUBLIC description: | - Determines who can see the dossier. Possible values include: + Specifies who can see the dossier. Possible values: - `PRIVATE`: Visible to dossier members only. - `PUBLIC`: Visible to all users. @@ -3121,7 +3129,7 @@ components: startDate: type: string format: date-time - description: The starting date for the lifecycle of this dossier. + description: The starting date of the dossier's lifecycle. dueDate: type: string format: date-time @@ -3129,19 +3137,19 @@ components: dossierStatusId: type: string format: uuid - description: The unique identifier of the current status of the dossier. The status definitions are managed in the dossier template. + description: The unique identifier of the current dossier status. The status definitions are managed in the dossier template. watermarkId: type: string format: uuid deprecated: true description: | - > **Note:** In DocuMine, watermarks are not supported. + > **Note:** DocuMine does not support watermarks. previewWatermarkId: type: string format: uuid deprecated: true description: | - > **Note:** In DocuMine, watermarks are not supported. + > **Note:** DocuMine does not support watermarks. dossierAttributes: $ref: '#/components/schemas/DossierAttributes' downloadFileTypes: @@ -3283,14 +3291,14 @@ components: type: string format: uuid description: | - The unique identifier of the dossier to update. This property needs to be null for create requests, + The unique identifier of the dossier to be updated. This property needs to be null for create requests, as the system will generate it automatically. If the value is not a valid identifier, the endpoint will return a `400 Bad request` error. name: type: string description: | A human-readable name for the dossier. The name must be unique among all dossiers - within the scope of the workspace (tenant). + within the workspace (tenant). description: type: string description: | @@ -3319,13 +3327,13 @@ components: approverIds: type: array description: | - An array of unique identifiers for users who have approval permission in the dossier. Needed if using an approval workflow. + An array of unique identifiers for users who have approval permission in the dossier. Needed if using a 2-step approval workflow. - > **Note:** The DocuMine application does not have an approval workflow and this **list can be left empty**. However, every member will be - > elevated to a privileged member to ensure full functionality. + > **Note:** DocuMine currently does not support the 2-step approval workflow and this **list can be left empty**. However, all members will be + > granted extended permissions to ensure full functionality. items: type: string - description: A unique identifier for a member with approval permission. + description: A unique identifier for a member holding the approval permission. uniqueItems: true reportTemplateIds: $ref: "#/components/schemas/ReportTemplateIdList" @@ -3358,7 +3366,7 @@ components: properties: id: description: | - A unique identifier for the component mapping metadata. It's generated automatically. Use this to retrieve a specific component mapping file. + A unique identifier for the component mapping metadata that is generated automatically. Use this identifier to retrieve a specific component mapping file. type: string name: description: | @@ -3458,11 +3466,11 @@ components: type: object properties: id: - description: A unique identifier for the component definition. + description: A unique identifier of the component definition. type: string format: uuid dossierTemplateId: - description: The ID of the dossier template to which this component belongs. + description: The ID of the dossier template this component is associated with. type: string technicalName: description: The technical name of the component. @@ -3474,10 +3482,10 @@ components: description: A brief description of the component. type: string rank: - description: The rank of the component within the template, used for ordering. + description: The rank of the component within the template, which is used to determin the order of the components. type: integer softDeleteTime: - description: The timestamp indicating when the component was soft deleted. If null, the component is not soft deleted. + description: The timestamp indicating when the component was soft deleted. If null, the component has not been soft deleted. type: string format: date-time required: @@ -3491,17 +3499,17 @@ components: dossierTemplateId: 8cd4b482-fb49-4315-9b51-789b4ae46c57 technicalName: study_conclusion displayName: Study Conclusion - description: The drawn conclusion from the performed study + description: The conclusion derived from the conducted study. rank: 1 softDeleteTime: null ComponentDefinitionAddRequest: description: | The ComponentDefinitionAddRequest object represents a request to create a component definition within a dossier template. - The rank will be automatically generated and does not need to be provided at creation. + The rank will be automatically generated and does not need to be included in the creation request. example: technicalName: study_conclusion displayName: Study conclusion - description: The conclusion of the study + description: The conclusion of the study. type: object properties: technicalName: @@ -3543,9 +3551,9 @@ components: DossierTemplate: description: | The `DossierTemplate` object represents the blueprint for creating and - managing dossiers and for handling and analyzing the files of dossiers. + managing dossiers, as well as for handling and analyzing the files contained in the dossiers. It contains various settings, rules, and metadata to control the behavior - of individual dossiers that get created based on this template. + of individual dossiers created on the basis of the template. example: id: 1e07cde0-d36a-4ab7-b389-494ca694a0cb name: DocuMine Example @@ -3576,15 +3584,15 @@ components: description: The user-defined name of the dossier template, required for create and update operations. type: string description: - description: A detailed description of the purpose and usage of this dossier template. + description: A detailed description outlining the purpose and usage of this dossier template. type: string dateAdded: - description: The date when this dossier template was first created. Automatically set by the system. + description: The date wof creation of this dossier template. Automatically set by the system. format: date-time type: string dateModified: description: | - The most recent date when modifications were made to this dossier template. + The date of the latest modifications to the dossier template. Automatically set by the system. format: date-time type: string @@ -3598,14 +3606,14 @@ components: format: uuid validFrom: description: | - The starting date for the validity of this dossier template. Dossiers can only be created - based on this template after this date. + The date from which this dossier template becomes valid. This date marks the earliest possible point for creating dossiers + using this template. format: date-time type: string validTo: description: | - The ending date for the validity of this dossier template. Dossiers will no longer be able to - be created based on this template after this date. + The expiration date of this dossier template. After this date, it will no longer be possible + to create dossiers using this dossier template. format: date-time type: string downloadFileTypes: @@ -3613,34 +3621,34 @@ components: status: description: | Indicates the current status of the dossier template: - * `INCOMPLETE`: The dossier template is missing some information or settings. Dossiers cannot be created based - on this template until the missing information and settings are added. - * `INACTIVE`: The dossier template cannot be used for creating dossiers based on it. - * `ACTIVE`: The dossier template can be used for creating dossiers based on it. + * `INCOMPLETE`: The dossier template is missing some information or settings. The required information + needs to be provided before dossiers can be created. + * `INACTIVE`: The dossier template cannot be used for creating dossiers. + * `ACTIVE`: The dossier template can be used for creating dossiers. enum: - INCOMPLETE - INACTIVE - ACTIVE type: string keepImageMetadata: - description: Flag indicating whether metadata from images in PDFs should be retained or removed. + description: Flag indicating whether metadata from images in PDFs shall be retained or removed. type: boolean keepHiddenText: - description: Flag indicating whether hidden text in PDFs should be retained or removed. + description: Flag indicating whether hidden text in PDFs shall be retained or removed. type: boolean keepOverlappingObjects: - description: Flag indicating whether overlapping objects in PDFs should be retained or flattened. + description: Flag indicating whether overlapping objects in PDFs shall be retained or flattened. type: boolean applyDictionaryUpdatesToAllDossiersByDefault: description: | Flag indicating whether updates to the dictionary should automatically be applied to all dossiers - created from this template. + created on the basis of this template. type: boolean ocrByDefault: - description: Flag specifying if OCR should be automatically applied to PDFs that get upload to dossiers based on this template. + description: Flag specifying whether OCR shall be automatically performed on PDFs uploaded to dossiers that use this template type: boolean removeWatermark: - description: Flag specifying if the system should try to remove watermarks in documents prior to OCR processing. + description: Flag specifying whether the system should try to remove watermarks from documents before performing OCR. type: boolean type: object DownloadFileTypes: @@ -3655,8 +3663,8 @@ components: - `ORIGINAL` Contrary to intuition, this is not the uploaded file, but the pre-processed, optimized PDF, which may also contain the OCR results. This is the PDF that used by the system for further processing. - - `PREVIEW` The annotated version of the PDF, highlighting the found entities that were - evaluated to extract the components. + - `PREVIEW` The annotated version of the PDF, highlighting the detected entities that were + evaluated for component extraction. items: enum: - ORIGINAL @@ -3665,12 +3673,12 @@ components: example: - ORIGINAL DossierTemplateList: - description: Represents a list of dossier templates, each encapsulating a set of rules and settings. + description: Represents a list of dossier templates, each defining a unique set of rules and configurations. example: dossierTemplates: - id: 1e07cde0-d36a-4ab7-b389-494ca694a0cb name: DocuMine Example - description: Typical settings for DocuMine. + description: Typical DocuMine settings. dateAdded: 2020-01-23T04:56:07.000+00:00 dateModified: 2021-01-23T04:56:07.000+00:00 createdBy: c2e33246-e50a-4c43-831c-6789a5637db6 @@ -3688,7 +3696,7 @@ components: - ORIGINAL - id: 8d8cae48-5c33-4617-ac27-1643f29b79d8 name: Another DocuMine Example - description: Typical settings for DocuMine. + description: Typical DocuMine settings. dateAdded: 2023-09-01T06:54:32.000+00:00 dateModified: 2023-09-01T06:54:32.000+00:00 createdBy: 46a7f9d3-6ba0-41d7-b312-b8e708aa6f4d @@ -3706,7 +3714,7 @@ components: - ORIGINAL properties: dossierTemplates: - description: Each entry is a dossier template with its details. + description: Each entry corresponds to a dossier template and includes further details about it. items: $ref: '#/components/schemas/DossierTemplate' type: array @@ -3720,10 +3728,10 @@ components: timestamp: type: string format: date-time - description: The exact date and time when the error was encountered. This can be useful for logging or troubleshooting. + description: The exact date and time the error ocurred. This information can be useful for logging or troubleshooting purposes. message: type: string - description: A detailed description of the error, providing insights on the problem and potentially how to resolve or avoid it. + description: A detailed description of the error, providing insights into the problem and guidance on potential resolutions or preventive measures. example: timestamp: "2023-09-21T12:45:00Z" message: "An error occurred while processing the request." @@ -3747,7 +3755,7 @@ components: properties: fileIds: type: array - description: A list of unique identifiers for the files to be deleted. + description: A list of unique identifiers of the files to be deleted. items: type: string description: The unique identifier of a file. @@ -3757,11 +3765,11 @@ components: - 1fdbd888b39059c8cf171df26f62f8a5 FileErrorInfo: type: object - description: Detailed information about an error encountered with a file. + description: Detailed information about a file-related error. properties: cause: type: string - description: The underlying reason or cause of the error. + description: The reason or root cause for the error. queue: type: string description: The queue or process where the error was encountered. @@ -3787,20 +3795,20 @@ components: dossierId: type: string format: uuid - description: The unique identifier linking the file to its associated dossier. + description: The unique identifier linking the filte to its respective dossier. dossierTemplateId: type: string format: uuid - description: The identifier of the dossier template of the file's dossier. + description: TThe identifier of the dossier template governing the dossier that contains the file. dossierStatusId: type: string format: uuid - description: The identifier of the dossier status of the file's dossier. + description: The identifier of the dossier status of the dossier containing the file. filename: description: The file's name. type: string dossierArchived: - description: Tells if the dossier of this file is archived or not. + description: Specifies whether the dossier containing the file is archived or not. type: boolean processingStatus: type: string @@ -3824,12 +3832,12 @@ components: - FIGURE_DETECTION_ANALYZING - TABLE_PARSING_ANALYZING description: | - The processing status of a file. The states give detailed information about the current processing step. - In general, this information is useful for debugging is the file is stuck in a status. + The processing status of a file. The status provides detailed information about the current processing step. + This information is particularly useful for debugging purposes if the file is stuck in a status: - The status `UNPROCESSED` indicates a newly uploaded file. Status `ERROR` indicates that the system could not - process the file for some reason. Finally, `PROCESSED` is what you usually expect as the final state after - all required processing steps are done. + - `UNPROCESSED`: Newly uploaded file. + - `ERROR`: System could not process the file for some reason. + - `PROCESSED`: Expected final status after all required processing steps are completed. workflowStatus: type: string enum: @@ -3840,11 +3848,11 @@ components: description: | The workflow status of a file. - As DocuMine does not have an approval workflow the meaning of the states is as follows: - - `NEW` - Initial status of the uploaded files. - - `UNDER_REVIEW` is actually not used in DocuMine. - - `UNDER_APPROVAL` means "In progress", i.e. a user is checking the extracted components. - - `APPROVED` means "Done", i.e. a user has checked and adjusted the components if necessary. + As DocuMine does not have an approval workflow the meaning of the statuses is as follows: + - `NEW` is the initial status of the uploaded files. + - `UNDER_REVIEW` is not used in DocuMine. + - `UNDER_APPROVAL` means "In progress", i.e. a user is reviewing the extracted components. + - `APPROVED` means "Done", i.e. a a user has reviewed and adjusted the components where necessary. numberOfPages: description: The number of pages of the file. format: int32 @@ -3862,10 +3870,10 @@ components: format: int32 type: integer assignee: - description: The current assignee's (if any) user id. + description: The user id of the current assignee (if any). type: string lastReviewer: - description: The last reviewer's (if any) user id. + description: The user id of the last revier (if any). type: string lastApprover: description: The user id of the last approver (if any). @@ -3881,61 +3889,59 @@ components: type: boolean hasUpdates: description: | - Shows if there is any change between the previous and current - analysis. + Shows whether there has been any change between the last and current analysis. type: boolean hasImages: description: Shows if any images were found during the analysis. type: boolean ocrStartTime: description: | - Shows if this file has been OCRed by us. Start time of OCR - Process + Shows whether the file has been OCRed by DocuMine. Start time of OCR process. format: date-time type: string numberOfPagesToOCR: - description: Number of pages to be OCRed by us + description: Number of pages to be OCRed by DocuMine. format: int32 type: integer numberOfOCRedPages: - description: Number of pages already OCRed by us + description: Number of pages already OCRed by DocuMine. format: int32 type: integer ocrEndTime: - description: Shows if this file has been OCRed by us. End time of OCR Process + description: Shows whether the file has been OCRed by DocuMine. End time of OCR process. format: date-time type: string hasAnnotationComments: - description: Shows if this file has comments on annotations. + description: Shows whether the file has comments on annotations. type: boolean uploader: description: The ID of the user who uploaded the file. type: string dictionaryVersion: - description: Shows which dictionary versions was used during the analysis. + description: Shows which dictionary versions were applied during the analysis. format: int64 type: integer rulesVersion: - description: Shows which rules versions was used during the analysis. + description: Shows which rules versions were applied during the analysis. format: int64 type: integer legalBasisVersion: - description: Shows which legal basis versions was used during the analysis. + description: Shows which legal basis versions were applied during the analysis. format: int64 type: integer excluded: - description: Shows if the file was excluded from analysis. + description: Shows whether the file was excluded from analysis. type: boolean lastProcessed: - description: Shows the last date of a successful analysis. + description: Shows the date of the last successful analysis. format: date-time type: string lastLayoutProcessed: - description: Shows the last date of a layout parsing. + description: Shows the date of the last layout parsing. format: date-time type: string approvalDate: - description: Shows the date of approval, if approved. + description: Shows the approval date if approved. format: date-time type: string lastUploaded: @@ -3950,12 +3956,11 @@ components: $ref: '#/components/schemas/FileAttributes' dossierDictionaryVersion: description: | - Shows which dossier dictionary versions was used during the - analysis. + Shows which dossier dictionary versions were applied during the analysis. format: int64 type: integer analysisRequired: - description: Shows if the file requires reanalysis. + description: Shows whether the file requires reanalysis. type: boolean excludedPages: description: Set of excluded pages for this file. @@ -3966,44 +3971,42 @@ components: type: array uniqueItems: true softDeletedTime: - description: Shows if the file is soft deleted. + description: Shows whether the file is soft deleted. format: date-time type: string lastFileAttributeChange: - description: Date and time when the files attributes was last updated. + description: Date and time of the last file attributes update. format: date-time type: string hasSuggestions: - description: Shows if there are any Suggestions in this file. + description: Shows whether the file contains any suggestions. type: boolean excludedFromAutomaticAnalysis: - description: Shows if the file is excluded from automatic analysis. + description: Shows whether the file is excluded from automatic analysis. type: boolean redactionModificationDate: - description: Shows the last redaction modification date of this file. + description: Shows the date of the last redaction modifications in this file. format: date-time type: string fileManipulationDate: - description: Shows the date of the last manipulation of this file. + description: Shows the date the file was last modified. format: date-time type: string lastManualChangeDate: description: | - Shows the date of the last manual change of an annotation of - this file. + Shows the date of the last manual change of an annotation in this file. format: date-time type: string hasHighlights: description: | - Shows if there are highlights to remove or convert for this - file. + Shows whether the file contains highlights that could be removed or converted. type: boolean fileSize: description: Size of the optimized, internally stored file. format: int64 type: integer analysisVersion: - description: Analysis Version. + description: Analysis version. format: int32 type: integer lastIndexed: @@ -4013,7 +4016,7 @@ components: fileErrorInfo: $ref: '#/components/schemas/FileErrorInfo' lastOCRTime: - description: Shows if this file has been OCRed by us. Last Time of OCR. + description: Shows whether the file has been OCRed by DocuMine. Time of the last OCR. format: date-time type: string example: @@ -4086,7 +4089,7 @@ components: properties: files: type: array - description: An array of status details for each individual file. + description: An array of status details for each file in the list. items: $ref: '#/components/schemas/FileStatus' example: @@ -4240,18 +4243,16 @@ components: type: array processedAttributes: description: | - List processed file attributes, in case the upload contained - a CSV. + List of processed file attributes, in case the upload included a CSV. items: description: | - List processed file attributes, in case the upload contained - a CSV. + List of processed file attributes, in case the upload included a CSV. type: string type: array processedFileIds: - description: List processed fileIds, in case the upload contained a CSV. + description: List of processed fileIds, in case the upload included a CSV. items: - description: List processed fileIds, in case the upload contained a CSV. + description: List of processed fileIds, in case the upload included a CSV. type: string type: array type: object @@ -4271,12 +4272,12 @@ components: format: int32 type: integer message: - description: The error or warning message that describes the details. + description: The error or warning message describing the error details. type: string type: object RuleValidation: description: | - Information about the uploaded rules file. The `error` field is empty if there were no validation errors in the uploaded rules file. + Information about the uploaded rules file. The `error` field remains empty if there were no validation errors in the uploaded rules file. example: errors: - line: 123 @@ -4317,9 +4318,9 @@ components: errorCause: type: string description: | - If the status is `FAILED`, this field contains information about the error that happened - while preparing the download package. This information is intended to be included in a - bug report if the error occurs repeatedly and indicates a general problem with the application. + If the status is `FAILED`, this field contains information about the error encountered + while preparing the download package. This information should be included in a bug report + if the error persists, as it may indicate a broader issue with the application. example: "" status: type: string @@ -4332,12 +4333,12 @@ components: description: | The status of the download file. In particular: - `QUEUED` - The download job has been created and is waiting to be processed by the system. - - `GENERATING` - The system currently creates the files for the download package. - - `COMPRESSING` - The system creates a ZIP archive that will contain all files of the download package. - - `READY` - The download package is ready for download. Please note that the download will be kept only - for a certain period. This period can be configured in the settings of your workspace. + - `GENERATING` - The system is currently creating the files for the download package. + - `COMPRESSING` - The system is generating a ZIP archive that will contain all files of the download package. + - `READY` - The download package is ready for download. Please note that the download will only be + retained for a certain period. This period can be configured in the settings of your workspace. - `FAILED` - An error occurred while preparing the download. The `errorCause` field might contain - additional details on the error. + additional details about the error. example: READY creationDate: type: string @@ -4357,13 +4358,13 @@ components: dossierId: type: string format: uuid - description: The identifier of the dossier to which the content of the download package belongs. + description: The identifier of the dossier corersponding to the content of the download package. example: 20354d7a-e4fe-47af-8ff6-187bca92f3f9 fileIds: type: array items: type: string - description: The list of file identifiers to which the content of the download package belongs. + description: The list of file identifiers corresponding to the content of the download package. example: - 51d3f70ac322c98dc4db70a2ac44115a - 1fdbd888b39059c8cf171df26f62f8a5 @@ -4402,11 +4403,11 @@ components: allOf: - $ref: '#/components/schemas/DownloadRequest' - type: object - description: Request payload to initiate the preparation of the download of multiple files. + description: Request payload to initiate the preparation for downloading multiple files. properties: fileIds: type: array - description: A list with unique identifiers of the files for which the download is to be prepared. + description: A list of the unique identifiers of the files that will be included in the download preparation. items: type: string description: The unique identifier of a file. @@ -4439,11 +4440,11 @@ components: uniqueItems: true type: array description: | - The roles of the user. In particular: - - `USER` - default user permission to work with the application - - `MANAGER` - additional privileges to create and manage dossiers - - `USER_ADMIN` - administration privileges limited to manage users only - - `ADMIN` - general administration privileges + The role(s) of the user. In particular: + - `USER` - default user permission for working with the application + - `MANAGER` - additional privileges for creating and managing dossiers + - `USER_ADMIN` - administration privileges limited to user management + - `ADMIN` - full administration privileges across the application items: type: string enum: @@ -4473,33 +4474,33 @@ components: startDate: type: string format: date-time - description: The starting date of the report. + description: The starting date of the report period. endDate: type: string format: date-time - description: The ending date of the report. + description: The ending date of the report period. numberOfAnalyzedFiles: type: integer format: int32 description: | - The count of files that have been analyzed in the requested period. The counter is - increased only once for each file, regardless of the number of analysis. + The number of files that have been analyzed in the requested report period. The counter increases + by one for each file, regardless of the number of analyses conducted. numberOfAnalyzedPages: type: integer format: int32 description: | - The count of pages that have been analyzed in the requested period. The counter is - increased only once for each file, regardless of the number of analysis. + The number of pages that have been analyzed in the requested period. The counter increases + by one for each file, regardless of the number of analyses conducted. analyzedFilesBytes: type: integer format: int64 description: | - The size in bytes of the files that have been analyzed in the requested period. - The counter is increased only once for each file, regardless of the number of analysis. + The size in bytes of the files that have been analyzed in the requested report period. + The counter increases by one for each file, regardless of the number of analyses conducted. totalFilesUploadedBytes: type: integer format: int64 - description: The total size in bytes of all present files at the end of the period. + description: The total size in bytes of all files resent at the end of the period. activeFilesUploadedBytes: type: integer format: int64 @@ -4516,18 +4517,18 @@ components: type: integer format: int32 description: | - The count of files that have undergone OCR (Optical Character Recognition) in the - requested period. + The number of files that have undergone OCR (Optical Character Recognition) in the + requested report period. numberOfOcrPages: type: integer format: int32 - description: The count of pages that have undergone OCR in the requested period. + description: The number of pages that have undergone OCR in the requested period. numberOfDossiers: type: integer format: int32 - description: The total number of present dossiers at the end of the period. + description: The total number of present dossiers at the end of the report period. monthlyData: - description: A list of data metrics categorized on a monthly basis. + description: A list of data metrics organized by month. items: $ref: '#/components/schemas/MonthlyReportData' type: array @@ -4565,22 +4566,22 @@ components: numberOfOcrPages: 1 LicenseReportRequest: type: object - description: Request object to retrieve a license report for a given date range. + description: Request object for retrieving a license report for a given reporting period. properties: startDate: type: string format: date-time - description: The start date for the requested report. + description: The start date of the requested report. endDate: type: string format: date-time - description: The end date for the requested report. + description: The end date of the requested report. example: startDate: 2000-01-01T00:00:00.000+00:00 endDate: 2001-01-01T00:00:00.000+00:00 MonthlyReportData: type: object - description: Detailed metrics regarding license usage for a given month. + description: Detailed license usage metrics for a particular month. properties: startDate: type: string @@ -4589,23 +4590,23 @@ components: endDate: type: string format: date-time - description: The ending date of the respective month. + description: The end date of the respective month. numberOfAnalyzedPages: type: integer format: int32 description: | - The count of pages that have been analyzed in the respective month. The counter is - increased only once for each file, regardless of the number of analysis. + The count of pages that have been analyzed in the respective month. The counter increases + by one for each file, regardless of the number of analyses conducted. analyzedFilesBytes: type: integer format: int64 description: | The size in bytes of the files that have been analyzed in the respective month. - The counter is increased only once for each file, regardless of the number of analysis. + The counter increases by one for each file, regardless of the number of analyses conducted. totalFilesUploadedBytes: type: integer format: int64 - description: The total size in bytes of all present files at the end of the respective month. + description: The total size in bytes of all files present at the end of the respective month. activeFilesUploadedBytes: type: integer format: int64 @@ -4621,7 +4622,7 @@ components: numberOfOcrPages: type: integer format: int32 - description: The count of pages that have undergone OCR in the requested respective month. + description: The number of pages that have undergone OCR in the requested report month. example: startDate: 2000-01-01T00:00:00.000+00:00 endDate: 2000-02-01T00:00:00.000+00:00 @@ -4634,12 +4635,12 @@ components: numberOfOcrPages: 1 UploadRequest: type: object - description: Request object to upload a file. + description: Request object for uploading a file. properties: file: type: string format: binary - description: The binary content of the file to be uploaded. + description: The binary data of the file to be uploaded. required: - file securitySchemes: