Uploading outbound documents

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

Main document flow

Uploading a document flow in Routty involves the following steps:

1. Request a Blob Storage URL: Use the input-api/input-documents endpoint to request a secure URL from Routty where your document can be uploaded to blob storage.

2. Upload Additional Attachments (Optional): If required, upload additional attachments before uploading the main document to ensure they are properly associated with the document.

3. Upload Document to Routty: Upload the document using the provided uploadUrl. The document must be in XML format.

4. Retrieve Document Status (Optional): After uploading, use the documentId to track the status and retrieve logs related to the document's processing.

5. Download Files (Optional): Retrieve any generated files or attachments related to the document from Routty.

6. Get List of Error Codes (Optional): Retrieve a list of known internal error codes.

7. Cancel Document (Optional): Cancels processing of document already in ERROR status.

The routingIdentifier simplifies route configuration, allowing automatic matching of routes based on shared identifiers, reducing the need for redundant setups.

Request Routty for a blob storage URL

Your connector needs to request Routty a URL, where the document can be uploaded to blob storage.

This can be done using the POST input-api/input-documents endpoint, which takes the following required parameters:

• x-correlation-id header: this is the ID of the document as provided by the source system. This ID is used throughout processing to identify your document.

• receivedOn: (Optional) This is the document creation date in UTC Timezone when the document was originally created. If not set, it defaults to the current date and time. The value must be less than or equal to the current time.

• routingIdentifier: (Optional) A string that allows route determination. If provided, the system will be able to match routes based on the routing identifier, using the Input Identifier in the route configuration.

Routty will respond with the uploadUrl, which is available for 30 minutes for uploading the document. Additionally, a documentId will be returned, which uniquely identifies the document within Routty.

The requested uploadUrl is valid for only 30 minutes.

Upload additional attachments to Routty

Additional attachment can only be uploaded before uploading the main document.

This step is optional but recommended to ensure the attachments are successfully added before the main document is processed by Routty.

All files uploaded as attachments will be included in the document processing.

To upload an attachment, use the POST input-api/upload-attachment endpoint, providing the following data in the body:

• documentId: The ID returned when requesting the upload URL.

• documentType: Defines the type of document. Possible values: Attachment, LegalDocument.

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

• fileContent: The content of the attachment, encoded in Base64

Upload your document to Routty

Authentication is not required for this API call, as the upload URL is secure and time-limited.

Using the uploadUrl received from the previous call, you can upload a single document to Routty by performing a PUT request to the URL. This call requires the following parameters:

• x-ms-blob-type header: Set this header to blockblob.

• Content-Type header:

  • For XML documents, set the header to application/xml.

  • For PDF documents, set the header to application/pdf.

PDF files must be in PDFA format, meaning the XML content should be embedded inside the PDF document.

• Request body: The document to be uploaded. For XML documents, this will be the raw XML. For PDF documents, this will be the PDF file containing embedded XML.

A HTTP 201 response will be returned for a successful upload.

Retrieve the status of a document

After requesting a blob storage URL and uploading a document, you can use the documentId to retrieve the status and logs of the document.

There are two endpoints available to retrieve the status of documents:

• GET /input-api/documents/{documentId}/status: Returns the status and audit trail for a single document.

• GET /input-api/documents/statuses: Returns the status and audit trail for a list of documents.

The response will include:

• Status: The current status of the document.

• ErrorCode: The error code if the document has an ERROR status. It is internal error code or External for errors coming from external systems.

• Assignee: The assignee of error if the document has an ERROR status.

• DocumentAuditLogs: An array containing audit logs with details such as timestamp, event, user, and message.

Here are the possible DocumentStatus values you can track:

Document Audit Logs

The DocumentAuditLog contains detailed logs of the document’s processing events, which help track what actions were performed on the document and who performed them. Each log entry includes:

• DateTime: The timestamp of the event.

• Event: The type of event that occurred (e.g., processing, error, success).

• User: The user who performed the action.

• Message: A message describing the action or event.

The possible DocumentAuditLogEvent values include:

Example Response

Here is an example of a response for retrieving document status:

{
  "documentId": "d9f2b49c-8b6a-4f39-99b7-d1b6c38a1be5",
  "status": "SUCCESS",
  "documentReference": "string",
  "companyName": "string",
  "companyNumber": "string",
  "errorCode": "string",
  "assignee": "string"
  "documentAuditLogs": [
    {
      "dateTime": "2025-04-29T14:30:00Z",
      "event": "PROCESS",
      "user": "system",
      "message": "Document processing started."
    },
    {
      "dateTime": "2025-04-29T14:35:00Z",
      "event": "SUCCESS",
      "user": "system",
      "message": "Document successfully processed."
    }
  ]
}

Download files from Routty

During processing, Routty generates and extracts several files. These files can be accessed and downloaded via the API using the following endpoint:

• GET /input-api/documents/{documentId}/files: Retrieve input, generated, and attachment files related to the document.

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

The response will include:

• status: The status of the document.

• files: An array of files associated with the document.

Each file object will include the following properties:

• fileName: The name of the file (excluding extension).

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

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

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

Get List of Error Codes

During document processing, an error may occur. When this happens, the document is placed in an ERROR status and assigned an error code. This can be either an internal error code or an external one (for errors originating from external systems).

To retrieve a list of all known internal error codes with their descriptions, use the following endpoint:

• GET /input-api/error-code-list: Returns a list of all known internal error codes.

Cancel Document

If a document encounters an error during processing, it will move to the ERROR status and be assigned an error code. Documents in this status can be cancelled via the API using the following endpoint:

• POST /input-api/documents/{documentId}/cancel: Cancels processing of a document that is currently in the ERROR status.

Note: You can only cancel documents that were uploaded through this connector.

The response structure is the same as the one returned by the document status retrieval endpoints.

Using the routingIdentifier

To simplify routing configuration in Routty, the routingIdentifier can be used. This identifier, which can be defined during the document upload, will be used during route determination. This eliminates the need for redundant route setups and simplifies the routing process.

The routingIdentifier is a string with a maximum length of 255 characters.

When combined with the Format, Company, Tenant, and Environment information, Routty can determine how the document should be processed and to which target system it should be sent.