Annotations Service#

Tip

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:

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

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

recursively: boolean, required
redactionConfiguration: object (RedactionConfiguration), required: This object contains the possible redactions allowed in a given file. See RedactionConfiguration for details.

Request sample#

A request should look something like this:

{
 "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.

{
  "errors": [
  {
    "field": "string",
    "code": "string",
    "args": {
      "property1": "string",
      "property2": "string"
      }
    }
  ]
}

401: User is not logged in.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

403: User does not have permission to access the resource.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

404: Item not found, or the user does not have access to it.

"string"

500: A server error.

"string"

default: An unexpected error occurred.

{
  "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

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:

{
  "annotations": {
  "itemId": "string",
  "type": "ANNOTATIONS_TYPE_UNSPECIFIED",
  "groupId": "string",
  "annotationsData": "string"
  }
}

Responses#

200: A successful response.

400: An invalid identifier.

{
  "errors": [
  {
    "field": "string",
    "code": "string",
    "args": {
    "property1": "string",
    "property2": "string"
      }
  }
  ]
}

401: User is not logged in.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

403: User does not have permission to access the resource.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

404: Item not found, or the user does not have access to it.

"string"

500: A server error.

"string"

default: An unexpected error occurred.

{
  "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

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:

{
   "body": "string"
}

Responses#

200: A successful response.

400: An invalid identifier.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

401: User is not logged in.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

403: User does not have permission to access the resource.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

404: Item not found, or the user does not have access to it.

"string"

500: A server error.

"string"

default: An unexpected error occurred.

{
  "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

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 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.

{
  "annotations": {
  "itemId": "string",
  "type": "ANNOTATIONS_TYPE_UNSPECIFIED",
  "groupId": "string",
  "annotationsData": "string"
  }
}

400: An invalid identifier.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

401: User is not logged in.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

403: User does not have permission to access the resource.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

404: Item not found, or the user does not have access to it.

"string"

500: A server error.

"string"

default: An unexpected error occurred.

{
  "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

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

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.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

401: User is not logged in.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

403: User does not have permission to access the resource.

{
  "errors": [
    {
      "field": "string",
      "code": "string",
      "args": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

404: Item not found, or the user does not have access to it.

"string"

500: A server error.

"string"

default: An unexpected error occurred.

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string",
      "property1": null,
      "property2": null
    }
  ]
}

Annotations Service

Contents

Annotations Service#

Perform Smart Redaction#

Authorizations#

Parameters#

Body Parameters#

Request sample#

Responses#

Update Annotations#

Authorizations#

Parameters#

Body Parameters#

Request sample#

Responses#

Apply Redaction#

Authorizations#

Parameters#

Body Parameters#

Request Sample#

Responses#

Get Annotations#

Authorizations#

Parameters#

Responses#

Delete Annotations#

Authorizations#

Parameters#

Responses#