Retrieving inbound documents

All calls should be authenticated, as explained in Using the Routty API

Main document flow

This process allows you to retrieve, acknowledge, and manage documents within Routty. The flow consists of the following main steps:

1. Retrieve the List of Available Documents: Use the GET /output-api/output-documents endpoint to fetch a list of documents available for pickup.

2. Download the Documents: Access the documents by using the downloadUrl provided in the response.

3. Provide Feedback: After downloading, you can provide feedback to Routty, including a technical acknowledgement and optional additional feedback.

4. Upload Attachments (Optional): You can upload additional attachments related to your document.

5. Download Associated Files (Optional): You can retrieve any generated or attached files related to the document.

Get the list of documents that can be retrieved from Routty

You can retrieve a list of documents that are available for pickup by using the GET /output-api/output-documents endpoint. This endpoint will return documents linked to the API key you are using.

• Polling Frequency: It is recommended that you poll the system with a maximum frequency of once every minute.

• Pagination: The endpoint supports optional pagination parameters to manage large sets of data. No other information is required in the request.

• Response: The API will respond with a list of available documents, each entry containing properties and a downloadUrl to access the document.

Retrieve the actual documents

No authentication is required for this API call, since a secure and time-limited URL has been generated through a previous API call.

Once you have the list of documents, you can download the actual document by making an HTTP GET request to the downloadUrl provided in the response from the previous step.

Provide feedback

Once you have retrieved the document, you can provide feedback to Routty using the documentId included in the response from the GET /output-api/output-documents endpoint. Routty supports two types of feedback:

Technical Acknowledgement Endpoint

• Purpose: This endpoint allows you to acknowledge that you have successfully retrieved the document via the API. This action will:

  • Write an audit entry for the document.

  • Remove the document from the list returned by GET /output-api/output-documents.

• Endpoint: PUT /output-api/output-documents/{documentId}/technical-acknowledgment

• Error Reporting: You can optionally include an errorCode and errorMessage in your request to indicate that something went wrong while retrieving the document. If you include these, set the successful property to false. This will place the document in the error queue for further handling in Routty.

Feedback Endpoint

• Purpose: After providing technical acknowledgement, you can optionally update the document with additional feedback.

• Endpoint: PUT /output-api/output-documents/{documentId}

• Feedback Data: You can include a message, which will be added to the audit trail, and optionally update the status with one of the following values:

  • OK: Document processed successfully.

  • NOK: Document failed to be processed in external system.

  • PENDING: Document is still in progress.

  • REJECTED: Document was rejected during processing in external system.

API Key Settings: Expect Feedback

• If "Expect Feedback" is Disabled: The connector can only send a Technical Acknowledgement. When the successful property is set to true, the document will be marked as processed, and the status will change to SUCCESS.

• If "Expect Feedback" is Enabled: You must use both endpoints:

  1. Technical Acknowledgement: First, the connector needs to confirm that the document was successfully downloaded. A success response here will set the document status to AWAITING_FEEDBACK.

  2. Feedback: Once the document was exported the connector can provide further feedback from the external system. This will allow the connector to send updates on the document's status, such as success or failure of the processing.

Upload additional attachments to Routty

As an optional step you can upload additional attachments, related to your document, to Routty.

All files uploaded here will be added as attachment to the main document, and are included in further processing of the document.

To upload attachment use the POST output-api/upload-attachment endpoint and provide following data in the body:

• documentId: The ID included in the response of the /output-api/output-documents endpoint.

• documentType: Defines what type of document this is. Possible values are Attachment and LegalDocument

• extension: Extension of the attachment (e.g. .pdf)

• fileContent: Content of the attachment, encoded using Base64

Download files from Routty

Routty generates and extracts several files during the document processing. These files can be accessed and downloaded via the following endpoint:

• Endpoint: GET /output-api/documents/{documentId}/files

• Purpose: Retrieve input, generated, and attachment files associated with a given document.

You can only retrieve files for documents that were uploaded through this connector.

The response will include:

• status: The current status of the document.

• files: An array of files related to the document, each containing:

  • fileName: The name of the file, excluding the extension.

  • type: The type of the file (e.g., Input, Output, Attachment).

  • extension: The file extension (e.g., .pdf).

  • downloadUrl: An Azure blob storage link to download the file.