################### Annotations Service ################### .. tip:: `OpenAPI Reference `__ Annotations allow the end user to create annotations and redact text or images on private or shared PDF documents, such as text blocks, free drawing and highlighed text, pre or self-made stamps, notes, lines and arrows. The endpoints included in this service are are: .. list-table:: :header-rows: 1 :widths: 10 45 45 * - METHOD - PATH - SUMMARY * - POST - /v1/annotations/{dataroomId}/perform-smart-redaction - Perform Smart Redaction * - POST - /v1/annotations/{dataroomId}/{itemId} - Update Annotations * - POST - Apply Redaction - /v1/annotations/{dataroomId}/{itemId}/apply-redaction * - GET - /v1/annotations/{dataroomId}/{itemId}/{annotationsType} - Get Annotations * - DELETE - /v1/annotations/{dataroomId}/{itemId}/{annotationsType} - Delete Annotations Perform Smart Redaction ======================= `POST /v1/annotations/{dataroomId}/perform-smart-redaction` This is the endpoint where smart redaction requests are sent. Authorizations -------------- ApiKeyAuth .. include:: ``ApiKeyAuth`` Parameters ---------- dataroomId: string, required The dataroom where the item is stored. They are generated automatically when a new dataroom is created. **Example:** netfiles.de/**ID-DATAROOM**/ Body Parameters --------------- itemsId: array of strings, required The annotated item's ID. They are generated automatically when a new item is created. **Example:** netfiles.de/ID-t85990881/**ID-ITEM** .. Is this correct? recursively: boolean, required .. What is this? redactionConfiguration: object (RedactionConfiguration), required This object contains the possible redactions allowed in a given file. See :ref:`RedactionConfiguration ` for details. Request sample -------------- A request should look something like this: .. code-block:: json { "itemIds": [ "string" ], "recursively": true, "redactionConfiguration": { "redactionType": "READACTION_TYPE_UNSPECIFIED", "redactPersonNames": true, "redactEmail": true, "redactPhoneNumbers": true, "redactCreditCards": true, "redactIbanBic": true, "redactOrganizations": true, "redactLocations": true, "redactDates": true, "redactTimes": true, "redactCurrency": true, "redactUrls": true, "redactIpv4": true, "redactIpv6": true, "redactMacAddress": true, "redactEvents": true, "redactFac": true, "redactGpe": true, "redactLaw": true, "redactNorps": true, "redactProducts": true, "redactWorkOfArt": true, "redactRegisterIds": true, "projectNames": [ "string" ], "companyNames": [ "string" ], "contractNames": [ "string" ], "customers": [ "string" ], "sellers": [ "string" ], "tenants": [ "string" ], "productNames": [ "string" ], "customDictionary": [ "string" ], "language": "string", "notifyAdminsOnRedaction": true, "userToNotifyOnRedaction": "string" } } Responses --------- **200: A successful response.** **400: An invalid identifier.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **401: User is not logged in.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **403: User does not have permission to access the resource.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **404: Item not found, or the user does not have access to it.** .. code-block:: json "string" **500: A server error.** .. code-block:: json "string" **default: An unexpected error occurred.** .. code-block:: json { "code": 0, "message": "string", "details": [ { "@type": "string", "property1": null, "property2": null } ] } Update Annotations ================== `POST /v1/annotations/{dataroomId}/{itemId}` Creates and updates the current user's annotations. Authorizations -------------- ApiKeyAuth .. include:: ``ApiKeyAuth`` Parameters ---------- dataroomId: string, required The dataroom where the item is stored. They are generated automatically when a new dataroom is created. **Example:** netfiles.de/**ID-DATAROOM** itemId: string, required The annotated item. They are generated automatically when a new item is created. **Example:** netfiles.de/ID-t85990881/**ID-ITEM** Body Parameters --------------- annotations: json, required This refers to a single annotation. The ``annotations_data`` contains the ``InstantJSON`` string from Nutrient's PSPDFKit, which means netfiles only stores the json string, while the third-party application deals with all the actual changes under the hood. You can learn more about Nutrient's model `here `__. **Important!** Each time an annotation is created, Nutirent generates a ``pdfId`` property, which does not allow new annotations to be documented in earlier versions of the same pdf file. If you find a ``pdfId`` property anywhere on the ``InstantJSON``, please remove it before using or saving. Request sample -------------- A request should look something like this: .. code-block:: json { "annotations": { "itemId": "string", "type": "ANNOTATIONS_TYPE_UNSPECIFIED", "groupId": "string", "annotationsData": "string" } } Responses --------- **200: A successful response.** **400: An invalid identifier.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **401: User is not logged in.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **403: User does not have permission to access the resource.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **404: Item not found, or the user does not have access to it.** .. code-block:: json "string" **500: A server error.** .. code-block:: json "string" **default: An unexpected error occurred.** .. code-block:: json { "code": 0, "message": "string", "details": [ { "@type": "string", "property1": null, "property2": null } ] } Apply Redaction =============== `POST /v1/annotations/{dataroomId}/{itemId}/apply-redaction` Saves a new pdf file with redactions to the server, then displays the redactions on the UI. This can only be done with original pdf files. Authorizations -------------- ApiKeyAuth .. include:: ``ApiKeyAuth`` Parameters ---------- dataroomId: string, required The dataroom where the item is stored. They are generated automatically when a new dataroom is created. dataroomId: string, required The dataroom where the item is stored. They are generated automatically when a new dataroom is created. **Example:** netfiles.de/**ID-DATAROOM** itemId: string, required The annotated item. They are generated automatically when a new item is created. **Example:** netfiles.de/ID-t85990881/**ID-ITEM** Body Parameters --------------- body: string, required The redacted pdf file in binary format. Request Sample -------------- A request sample would look something like this: .. code-block:: json { "body": "string" } Responses --------- **200: A successful response.** **400: An invalid identifier.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **401: User is not logged in.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **403: User does not have permission to access the resource.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **404: Item not found, or the user does not have access to it.** .. code-block:: json "string" **500: A server error.** .. code-block:: json "string" **default: An unexpected error occurred.** .. code-block:: json { "code": 0, "message": "string", "details": [ { "@type": "string", "property1": null, "property2": null } ] } Get Annotations =============== `GET /v1/annotations/{dataroomId}/{itemId}/{annotationsType}` Returns the desired annotations on the UI. Authorizations -------------- ApiKeyAuth .. include:: ``ApiKeyAuth`` Parameters ---------- dataroomId: string, required The dataroom where the item is stored. They are generated automatically when a new dataroom is created. **Example:** netfiles.de/**ID-DATAROOM** itemId: string, required The annotated item. They are generated automatically when a new item is created. **Example:** netfiles.de/ID-t85990881/**ID-ITEM** annotationsType: string, enum, required The annotation types can be ``ANNOTATIONS_TYPE_UNSPECIFIED``, ``ANNOTATIONS_TYPE_PRIVATE``, ``ANNOTATIONS_TYPE_GROUP``, ``ANNOTATIONS_TYPE_PUBLIC``, or ``ANNOTATIONS_TYPE_REDACT``. ``ANNOTATIONS_TYPE_UNSPECIFIED`` are default. See :ref:`AnnotationsType `. - ``ANNOTATIONS_TYPE_PRIVATE``, or private annotations, are used when only the current user can see their own private annotations. Can be made on **original pdfs** or on **pdfs generated from docs**. - ``ANNOTATIONS_TYPE_PUBLIC``, also known as shared annotations, are used when annotations are shared between all users with the correct rights to the specific dataroom. When selected on the UI, the ``ANNOTATIONS_TYPE_PRIVATE`` are hidden from other users, displaying only the shared annotations. Can be made on **original pdfs** or on **pdfs generated from docs**. - ``ANNOTATIONS_TYPE_GROUP`` are never used. But you might, who knows. - ``ANNOTATIONS_TYPE_REDACT`` are used to select text or an area of a document for redaction. Area redactions are used for images. Responses --------- 200: A successful response. If sucessful, you will get a json file with your requested annotations. .. code-block:: json { "annotations": { "itemId": "string", "type": "ANNOTATIONS_TYPE_UNSPECIFIED", "groupId": "string", "annotationsData": "string" } } **400: An invalid identifier.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **401: User is not logged in.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **403: User does not have permission to access the resource.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **404: Item not found, or the user does not have access to it.** .. code-block:: json "string" **500: A server error.** .. code-block:: json "string" **default: An unexpected error occurred.** .. code-block:: json { "code": 0, "message": "string", "details": [ { "@type": "string", "property1": null, "property2": null } ] } Delete Annotations ================== `DELETE /v1/annotations/{dataroomId}/{itemId}/{annotationsType}` Deletes a certain type of annotation, either ``ANNOTATIONS_TYPE_PRIVATE`` or ``ANNOTATIONS_TYPE_PUBLIC``. Authorizations -------------- ApiKeyAuth .. include:: ``ApiKeyAuth`` Parameters ---------- dataroomId: string, required The dataroom where the item is stored. They are generated automatically when a new dataroom is created. **Example:** netfiles.de/**ID-DATAROOM** itemId: string, required The annotated item. They are generated automatically when a new item is created. **Example:** netfiles.de/ID-t85990881/**ID-ITEM** annotationsType: string, enum, required The annotation types can be ``ANNOTATIONS_TYPE_UNSPECIFIED``, ``ANNOTATIONS_TYPE_PRIVATE``, ``ANNOTATIONS_TYPE_GROUP``, ``ANNOTATIONS_TYPE_PUBLIC``, or ``ANNOTATIONS_TYPE_REDACT``. ``ANNOTATIONS_TYPE_UNSPECIFIED`` are default. See :ref:`AnnotationsType `. - ``ANNOTATIONS_TYPE_PRIVATE``, or private annotations, are used when only the current user can see their own private annotations. Can be made on **original pdfs** or on **pdfs generated from docs**. - ``ANNOTATIONS_TYPE_PUBLIC``, also known as shared annotations, are used when annotations are shared between all users with the correct rights to the specific dataroom. When selected on the UI, the ``ANNOTATIONS_TYPE_PRIVATE`` are hidden from other users, displaying only the shared annotations. Can be made on **original pdfs** or on **pdfs generated from docs**. - ``ANNOTATIONS_TYPE_GROUP`` are never used. But you might, who knows. - ``ANNOTATIONS_TYPE_REDACT`` are used to select text or an area of a document for redaction. Area redactions are used for images. Responses --------- **200: A successful response.** **400: An invalid identifier.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **401: User is not logged in.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **403: User does not have permission to access the resource.** .. code-block:: json { "errors": [ { "field": "string", "code": "string", "args": { "property1": "string", "property2": "string" } } ] } **404: Item not found, or the user does not have access to it.** .. code-block:: json "string" **500: A server error.** .. code-block:: json "string" **default: An unexpected error occurred.** .. code-block:: json { "code": 0, "message": "string", "details": [ { "@type": "string", "property1": null, "property2": null } ] }