Complete example to add redact annotations

In this page we will detail how to create redact annotations from the document transformations REST API.

Redact annotation on a given text

Here, we will use the text "Test business" as an example. To redact a specific text in the document, we first need to retrieve the position related to.

Retrieving the position of a text

To retrieve the position of the text, the searchText endpoint is used.

curl -X 'GET' \
 'http://localhost:8761/documents/b64_bXlkb2N1ZW1udA==/pages/0/text?searchText=Test%20business&caseSensitive=false&accentSensitive=false&regex=false' \
  -H 'accept: */*'

We are working here on the first page of the document b64_bXlkb2N1ZW1udA==

The result tells us the position of the desired text:

{
  "searchResults": [
    {
      "positionText": {
        "pageNumber": 0,
        "position": {
          "x": 42.52,
          "y": 245.07303,
          "w": 55.264004,
          "h": 12.0
        },
        "text": "Test Business",
        "individualWidths": [
          5.3768005,
          4.8927994,
          4.4000015,
          2.4463997,
          2.4463997,
          5.869602,
          4.8927994,
          4.4000015,
          1.953598,
          4.8927994,
          4.8927994,
          4.4000015,
          4.4000015
        ],
        "fontSize": 8.0,
        "font": "JQRQXM+Helvetica",
        "clickableDestination": null,
        "paragraphId": 3,
        "rightToLeftText": false,
        "startTime": -1.0,
        "rotation": 0
      },
      "textRangeList": [
        {
          "firstCharacter": 0,
          "lastCharacter": 12
        }
      ]
    }
  ]
}

Create the redact annotation

Now, we know that the position of the text corresponds to:

{
  "x": 42.52,
  "y": 245.07303,
  "w": 55.264004,
  "h": 12.0
}

Let's apply these coordinates to the annotation creation template:

curl -X 'POST' \
  'http://localhost:8761/transformations' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "annotations": {
    "annotations": [
      {
        "type": "com.arondor.viewer.annotation.api.RedactTextElemType",
        "documentId": {
          "id": "b64_bXlkb2N1ZW1udA=="
        },
        "page": 0,
        "id": {
          "id": "non-null-value"
        },
        "coords": [
          {
            "x": 42.52,
            "y": 245.07303,
            "w": 55.264004,
            "h": 12.0
          }
        ],
        "color": {
          "r": 0,
          "g": 0,
          "b": 0
        }
      }
    ]
  },
  "format": "pdf",
  "transformationDetails": [
    {
      "transformationElements": [
        {
          "documentId": "b64_bXlkb2N1ZW1udA==",
          "pagesSelectionList": [
            {
              "maxPage": 1,
              "minPage": 1
            }
          ]
        }
      ],
      "documentTitle": "MyDocument"
    }
  ]
}'

The result gives the id of the transformation:

{
  "transformationOrderId": {
    "id": "7325e176-400c-460b-b51e-a8026b78c62a"
  }
}

Retrieve information from the transformation

Let's retrieve the document id via the previously requested transformation order: 7325e176-400c-460b-b51e-a8026b78c62a

curl -X 'GET' \
  'http://localhost:8761/transformations/7325e176-400c-460b-b51e-a8026b78c62a' \
  -H 'accept: */*'

Result: here we retrieve the transformationResultDocumentID corresponding to b64_NGZlMWJlMTktNGYyNS00MjAzLWI1ZGQtNGNiYTkxMmI0OGIx

{
  "transformationOrderId": {
    "id": "71266b11-2016-4bb6-bcd8-562cf6ca6760"
  },
  "transformationDetails": [
    {
      "transformationElements": [
        {
          "documentId": {
            "id": "b64_bXlkb2N1ZW1udA=="
          },
          "documentTitle": null,
          "pagesSelectionList": [
            {
              "minPage": 1,
              "maxPage": 1
            }
          ]
        }
      ],
      "documentTitle": "test123"
    }
  ],
  "currentState": "PROCESSED",
  "transformationResultDocumentID": {
    "id": "b64_NGZlMWJlMTktNGYyNS00MjAzLWI1ZGQtNGNiYTkxMmI0OGIx"
  },
  "annotations": {
    "annotations": [
      {
        "type": "com.arondor.viewer.annotation.api.SquareElemType",
        "color": null,
        "date": null,
        "flags": null,
        "id": null,
        "documentId": {
          "id": "b64_bXlkb2N1ZW1udA=="
        },
        "lastModifier": null,
        "page": 0,
        "position": {
          "x": 42.52,
          "y": 245.07303,
          "w": 55.264004,
          "h": 12.0
        },
        "creator": null,
        "creationDate": null,
        "opacity": null,
        "subject": null,
        "security": null,
        "startTime": -1.0,
        "endTime": -1.0,
        "contentsRichtext": null,
        "contents": null,
        "popup": null,
        "fringe": null,
        "interiorColor": {
          "r": 0,
          "g": 0,
          "b": 0
        },
        "width": null,
        "dashes": null,
        "style": null,
        "intensity": null
      }
    ]
  },
  "format": "pdf",
  "errorMessage": null,
  "queuedDate": "2024-08-07T14:28:51.188+02:00",
  "processedDate": "2024-08-07T14:28:51.237+02:00",
  "queuedTime": 3,
  "processingTime": 45
}

Download the document from its ID

Now that we have the document id b64_NGZlMWJlMTktNGYyNS00MjAzLWI1ZGQtNGNiYTkxMmI0OGIx we can download it:

curl -X GET \
  'http://localhost:8761/documents/b64_NGZlMWJlMTktNGYyNS00MjAzLWI1ZGQtNGNiYTkxMmI0OGIx/file?format=pdf' \
  -o my_pdf.pdf

This downloaded document has the desired redacted annotation.

Other way to create redact annotations

Create a redact annotation in the defined zone

The annotation creation template can directly be used to create a annotation in a zone. To create an annotation at the positions {"x":35.0,"y":25.0,"w":160.0,"h":25.0} the call is:

curl -X 'POST' \
  'http://localhost:8761/transformations' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "annotations": {
    "annotations": [
      {
        "type": "com.arondor.viewer.annotation.api.RedactElemType",
        "documentId": {
          "id": "b64_bXlkb2N1ZW1udA=="
        },
        "page": 0,
        "id": {
          "id": "non-null-value"
        },
        "position": {
          "x": 35.0,
          "y": 25.0,
          "w": 160.0,
          "h": 25.0
        },
        "interiorColor": {
          "r": 0,
          "g": 0,
          "b": 0
        }
      }
    ]
  },
  "format": "pdf",
  "transformationDetails": [
    {
      "transformationElements": [
        {
          "documentId": "b64_bXlkb2N1ZW1udA==",
          "pagesSelectionList": [
            {
              "maxPage": 1,
              "minPage": 1
            }
          ]
        }
      ],
      "documentTitle": "MyDocument"
    }
  ]
}'

Create a redact annotation based on a rule

We can create the annotations based on rules. As example: be able to redact all amounts in a document. This regex is then used: ($[0-9]+(.[0-9]+)?)

We first need to use the URL encoding to the given regex to get: %28%5C%24%5B0-9%5D%2B%28.%5B0-9%5D%2B%29%3F%29

curl -X 'GET' \
  'http://localhost:8761/documents/b64_bXlkb2N1ZW1udA==/pages/0/text?searchText=%28%5C%24%5B0-9%5D%2B%28.%5B0-9%5D%2B%29%3F%29&caseSensitive=false&accentSensitive=false&regex=true' \
   -H 'accept: */*'

The result tells us all the positions of the matching text, now we can use the annotation creation template, as seen previously, to create the desired annotations.