.png)
Rossum Integration Guide
Connect Rossum’s document-processing workflows with enterprise applications through REST APIs, selected event callbacks, file exchange, and orchestrated data synchronization.
Rossum integration options at a glance
Rossum’s primary integration mechanism is a token-authenticated REST API for uploading documents, retrieving annotations and pages, managing queues and schemas, and interacting with hooks and related configuration. Rossum also supports selected webhook-style callbacks for document-processing and lifecycle events, although coverage and retry behavior should be confirmed for each tenant. Document extraction is asynchronous, so integrations commonly combine uploads with polling, callbacks, pagination, and reconciliation. File submission and source-content retrieval are supported through relevant API resources. Martini can orchestrate these steps, store correlation identifiers, transform annotation data, validate business rules, and deliver approved results to downstream systems.
| Integration point | Supported by Rossum? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Rossum’s primary programmatic interface supports document upload, annotation retrieval and updates, queue and schema management, hooks, users, pagination, and lifecycle actions where permitted. | Martini can consume the Rossum REST API, generate requests from configured API definitions, map responses, and orchestrate multi-step workflows. |
| Webhooks / outbound callbacks | Limited | Configured hooks or callbacks can notify external systems about selected document-processing, annotation, review, or approval events. | Martini can expose or consume HTTP endpoints for supported callbacks, acknowledge quickly, deduplicate notifications, and move processing into workflows. |
| Bulk / async / batch APIs | Limited | Document extraction is asynchronous, and collections support pagination; a universal bulk API for all Rossum resources was not confirmed. | Martini can implement upload-and-poll workflows, bounded concurrency, pagination checkpoints, queue-based processing, timeouts, and reconciliation. |
| File / attachment APIs | Yes | Rossum APIs support submitting document files and retrieving source or processed content where supported by the relevant resource. | Martini can validate files, send supported content, preserve identifiers and checksums, and deliver original files or extracted data to downstream systems. |
| Authentication | Yes | API access uses token-based authentication, including bearer-token patterns, with permissions controlling access to tenant resources. | Martini can keep tokens and callback secrets in secure environment configuration and apply configured authorization to API calls and exposed endpoints. |
| Pagination | Yes | Rossum API collections should be retrieved through documented pagination fields or links rather than assuming one response contains all resources. | Martini workflows can follow pagination, persist checkpoints, limit page size, and resume long-running synchronization safely. |
| Database / analytics access | Not confirmed | No direct Rossum database or database-access API was confirmed; integrations should use supported APIs and event mechanisms. | Martini can persist integration state in an approved external database when needed, without connecting directly to Rossum’s service database. |
| SDKs | Not confirmed | A vendor-maintained SDK covering all Rossum integration scenarios was not confirmed. | Martini can consume Rossum REST resources directly without requiring a dedicated Rossum SDK. |
How Rossum exposes data and business events
Rossum REST APIs
Rossum’s REST API is the primary documented interface for uploading documents, retrieving annotations and pages, managing queues and schemas, and interacting with hooks, users, and related resources. Collections are paginated and document processing is asynchronous.
Martini implementation pattern
Martini implementation pattern: a workflow authenticates to Rossum, submits or retrieves resources, stores Rossum identifiers and correlation state, follows pagination, maps responses into a canonical model, and invokes downstream APIs or persistence targets.
Implementation sequence
Rossum webhook-style callbacks
Rossum supports configured hooks and callback-based notifications for selected processing and lifecycle events. Coverage is not universal across all objects or events, and payload, retry, and status semantics should be verified for the tenant.
Martini implementation pattern
Martini implementation pattern: expose a controlled HTTP endpoint for supported Rossum notifications, acknowledge quickly, validate the incoming request where configured, and start a workflow that retrieves the authoritative annotation before processing.
Implementation sequence
Rossum asynchronous processing
Rossum document extraction generally does not complete in the initial upload request. Integrations must distinguish upload acceptance, extraction, human review, approval, rejection, and final export states.
Martini implementation pattern
Martini implementation pattern: separate submission from completion processing, use callbacks where available, poll with bounded intervals when necessary, and retain a scheduled reconciliation path for missed notifications or stalled documents.
Implementation sequence
Rossum file handling
Rossum supports document ingestion and source-file handling through relevant API resources. PDF and image files are common in document-processing workflows, while exact formats, size limits, and endpoints depend on the current API reference.
Martini implementation pattern
Martini implementation pattern: receive files from an upstream source, validate MIME type and size, submit them to Rossum, retain checksums and identifiers, and deliver the original file, extracted JSON, or both according to the target contract.
Implementation sequence
Common Rossum integration patterns
Pattern 1: Process invoices into an ERP
When to use this pattern
Use this pattern when invoice files arrive from email, file transfer, or an upstream application and must be extracted, reviewed, validated, and created in an ERP such as SAP S/4HANA or NetSuite.
Integration direction
Example Mapping
| Rossum Field | Canonical Field | Target Field |
|---|---|---|
| supplier_name | supplierName | Supplier |
| invoice_number | invoiceNumber | External invoice number |
| invoice_date | invoiceDate | Invoice date |
| total_amount | totalAmount | Gross amount |
Martini implementation pattern
Martini receives and validates the file, submits it to a Rossum queue, persists document and annotation identifiers, then polls or receives a selected event. After review or approval, the workflow maps the annotation, validates supplier, tax, currency, totals, and purchase-order references, checks for duplicates, and creates the ERP invoice. Transient API failures are retried with bounded backoff; permanent validation failures are routed to an exception workflow.
Martini capabilities used
- workflows
- API consumption
- file handling
- data mapping
- business rules
- error handling
Pattern 2: Synchronize approved annotations to accounting
When to use this pattern
Use this pattern when Rossum is the extraction and review layer and an accounting platform should receive only approved or finalized invoice data and supporting documents.
Integration direction
Example Mapping
| Rossum Field | Canonical Field | Target Field |
|---|---|---|
| annotation.id | sourceAnnotationId | Integration reference |
| supplier.name | vendorName | Vendor |
| currency | currencyCode | Currency |
| line_items | invoiceLines | Expense or item lines |
Martini implementation pattern
A Rossum callback or scheduled workflow identifies candidate annotations, then retrieves the latest authoritative annotation before writing to NetSuite. Martini applies approval-state and idempotency rules, transforms nested line items and monetary values, submits the accounting request, stores the target identifier, and supports reconciliation for delayed or missed callbacks.
Martini capabilities used
- event-driven workflows
- scheduled workflows
- API consumption
- data mapping
- idempotency rules
- monitoring
Pattern 3: Validate extracted documents with an external service
When to use this pattern
Use this pattern when extracted supplier, tax, purchase-order, or address data must be checked against another API before a document is approved or exported.
Integration direction
Example Mapping
| Rossum Field | Canonical Field | Target Field |
|---|---|---|
| supplier_name | supplierName | Validation request name |
| tax_number | taxIdentifier | Validation request identifier |
| purchase_order_number | purchaseOrderNumber | Purchase-order lookup key |
| total_amount | totalAmount | Validation request amount |
Martini implementation pattern
Martini retrieves the annotation after extraction, calls the external validation service, combines the result with Rossum fields, and applies business rules for pass, review, or rejection. The workflow records the validation response and correlation identifiers, retries transient validation failures, and prevents repeated downstream actions.
Martini capabilities used
- workflows
- API consumption
- data transformation
- business rules
- conditional routing
- error handling
Pattern 4: Reconcile incomplete and rejected documents
When to use this pattern
Use this pattern when callbacks may be delayed or lost, documents remain incomplete, or Rossum status must be compared with ERP or procurement records.
Integration direction
Example Mapping
| Rossum Field | Canonical Field | Target Field |
|---|---|---|
| document.id | rossumDocumentId | Source document reference |
| annotation.status | processingStatus | Integration status |
| queue.id | queueId | Processing queue |
| annotation.updated_at | lastSourceUpdate | Last synchronized time |
Martini implementation pattern
A scheduled Martini workflow retrieves paginated Rossum annotations in relevant states, compares them with stored ERP references, and routes missing or inconsistent items to an exception queue. Corrected or approved annotations are reprocessed using stored correlation keys, while checkpoints, retry counts, and final outcomes support safe replay.
Martini capabilities used
- scheduler triggers
- pagination handling
- database persistence
- business rules
- reconciliation
- error handling
Applications commonly integrated with Rossum
Rossum can be integrated with named enterprise applications to move extracted document data into finance, procurement, customer, workflow, and automation processes. These are typical architecture patterns rather than claims of universal Rossum-native integrations; product-specific API availability should be confirmed for each deployment.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| SAP S/4HANA | Transfer extracted and approved supplier invoice data and supporting documents into accounts-payable processes. | Rossum → Martini → SAP S/4HANA | Martini receives a Rossum callback or polls for approved annotations, retrieves the latest annotation and source file, validates supplier, tax, currency, totals, and purchase-order references, then creates or updates the SAP invoice with correlation and retry handling. |
| NetSuite | Create or update vendor bills, invoices, and supporting document attachments from Rossum annotations. | Rossum → Martini → NetSuite | A Martini workflow retrieves finalized Rossum annotations, applies duplicate checks using source and annotation identifiers, maps fields to the NetSuite payload, and records the target identifier for reconciliation. |
| Microsoft Dynamics 365 | Send extracted invoice and purchase-document data into finance and supply-chain workflows. | Rossum → Martini → Microsoft Dynamics 365 | Martini submits documents to Rossum when required, monitors processing state, transforms approved annotations into Dynamics 365 structures, and routes validation or downstream API failures for retry or exception handling. |
| Coupa | Transfer captured invoice information into procurement and accounts-payable processes. | Rossum → Martini → Coupa | Martini correlates Rossum annotations with procurement references, validates totals and supplier data, sends approved invoice data to Coupa, and persists processing status for replay-safe reconciliation. |
| Workday | Move supplier invoice or expense-related document data into financial workflows. | Rossum → Martini → Workday | A workflow retrieves completed annotations, maps nested fields and financial values to Workday requests, applies required-field rules, and handles transient failures with bounded retries. |
| Salesforce | Attach extracted customer, billing, or case-related document information to Accounts, Contacts, Opportunities, or Cases. | Rossum → Martini → Salesforce | Martini accepts a document from Salesforce or another source, submits it to a Rossum queue, and later maps the reviewed annotation and source-file reference back to the related Salesforce object. |
| ServiceNow | Create or update requests, cases, or document-processing tasks for extraction exceptions and operational follow-up. | Rossum → Martini → ServiceNow | Martini receives selected Rossum status events, enriches exception details with the current annotation, creates or updates a ServiceNow task, and prevents duplicates using Rossum resource identifiers. |
| UiPath | Combine Rossum extraction with robotic automation for legacy applications or desktop-based downstream workflows. | Rossum → Martini → UiPath | Martini coordinates document submission and extraction, normalizes the annotation output, and invokes or receives UiPath process data while retaining status, correlation, and failure details. |
How to build a Rossum integration in Martini
Objective
Establish Rossum access with tenant-approved token authentication and keep credentials, callback secrets, and environment-specific configuration outside workflow logic.
Instructions in Martini
- Configure the Rossum base URL and authorization headers
- Store tokens and secrets in secure environment configuration
- Use separate credentials and queues for development, testing, and production where possible
- Confirm permissions for queues, documents, annotations, and administrative resources
Objective
Select an event-driven, scheduled, or API-led entry point based on the Rossum lifecycle event and the reliability requirements of the integration.
Instructions in Martini
- Use a Rossum callback for supported selected events
- Expose a Martini API when another application submits documents
- Use a scheduler for polling and reconciliation
- Define timeout and fallback behavior for asynchronous processing
Objective
Submit or retrieve Rossum documents and annotations while preserving identifiers, pagination state, and source correlation data.
Instructions in Martini
- Validate source files before upload
- Store document, annotation, queue, and schema identifiers
- Follow documented pagination fields or links
- Retrieve the authoritative annotation after callbacks rather than trusting a notification payload alone
Objective
Separate document submission, extraction, review, approval, export, and reconciliation into maintainable workflow stages.
Instructions in Martini
- Model processing states explicitly
- Use callbacks to start lightweight workflows
- Move lengthy retrieval and downstream processing out of the callback request
- Persist checkpoints and correlation identifiers between stages
Objective
Transform Rossum annotation structures into a canonical model and target-specific payloads while handling schema variation and optional fields.
Instructions in Martini
- Map nested annotation fields and line items
- Validate supplier, tax, currency, totals, and purchase-order references
- Handle absent optional fields and schema differences by queue
- Normalize dates, decimals, currency, and locale-specific values
Objective
Create or update the target invoice, document, case, or validation result only after the required Rossum state and business checks are satisfied.
Instructions in Martini
- Check for an existing target identifier before creating a new object
- Send the transformed payload to the downstream API or persistence layer
- Attach the original file when the target requires it
- Store downstream identifiers and final processing status
Common Rossum data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Queues | Organize document-processing workspaces and define processing workflows. | SAP S/4HANA, NetSuite, Coupa, Microsoft Dynamics 365 | Martini uses queue identifiers when submitting documents, routes mappings by queue or schema, and stores them for correlation and reconciliation. |
| Documents | Represent uploaded source files submitted for extraction and processing. | Email or file sources, ERP platforms, Salesforce, UiPath | Martini validates and uploads files, preserves source identifiers and checksums, and retrieves source content when downstream systems require it. |
| Annotations | Represent extracted and reviewed structured data such as invoices and receipts. | SAP S/4HANA, NetSuite, Workday, Coupa, Microsoft Dynamics 365 | Martini retrieves annotations, maps nested fields into canonical models, validates required values, and applies approval and idempotency rules. |
| Pages | Represent individual pages or source content associated with a document or annotation. | Document repositories, ERP attachments, audit systems | Martini retrieves page or source content where supported, associates it with the parent document, and forwards it as an attachment or archived artifact. |
| Schemas | Define the fields and structures Rossum extracts from documents. | Canonical data models, finance applications, validation services | Martini uses schema-aware mappings, tolerates optional fields, validates required fields, and versions transformations when schemas change. |
| Hooks | Configure processing or integration actions that invoke external logic or endpoints. | Martini APIs, validation services, ServiceNow, downstream finance applications | Martini can receive supported callbacks, acknowledge them promptly, deduplicate by resource and event identifiers, and launch asynchronous workflows. |
Authentication and security considerations
Token-based API access
Rossum API access uses tokenized authentication, including bearer-token patterns and, depending on tenant configuration, JWT or API and access tokens. Permissions determine which queues, documents, annotations, and administrative resources an integration can access.
Protect credentials and documents
- Store Rossum tokens and callback secrets in Martini secure environment configuration.
- Use least-privilege users, teams, and organization permissions where available.
- Separate development, testing, and production credentials and queues.
- Avoid logging access tokens or full invoice documents unnecessarily.
- Protect source files and extracted data because they may contain financial, personal, or supplier-sensitive information.
Operational considerations for Rossum integrations
Asynchronous state and pagination
Document processing is asynchronous. Model upload, extraction, review, approval, rejection, and export separately, and follow Rossum pagination rather than assuming one response contains all resources.
Reliability and duplicate prevention
- Use stable source, document, annotation, or file-hash identifiers for idempotency.
- Expect callback retries or duplicate notifications and retrieve the authoritative resource before processing.
- Apply exponential backoff for temporary failures, including applicable 429 and transient 5xx responses.
- Use bounded polling, concurrency limits, timeouts, and scheduled reconciliation.
Schema and testing
Rossum schemas and annotation fields can vary by queue and evolve over time. Validate required fields, tolerate optional values, normalize financial formats, and test mappings against representative annotations before deployment.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration beyond a single API call
Rossum integrations commonly require file submission, asynchronous status tracking, annotation retrieval, human-review rules, validation services, downstream writes, and reconciliation. Martini provides workflows and APIs for coordinating these stages without embedding the entire process in a single script.
Maintainable transformation and control
- Centralize mappings, validation, business rules, and reusable integration logic.
- Expose controlled APIs for internal applications while consuming Rossum APIs securely.
- Use the same workflow model for callbacks, scheduled polling, and exception recovery.
- Capture correlation IDs, statuses, retries, and downstream identifiers for operational support.
Frequently asked questions
Rossum can be integrated through its REST API for document submission, annotation retrieval, field updates, queue and schema management, and related configuration. Selected document-processing and lifecycle events can also use configured hooks or webhook-style callbacks. Because extraction is asynchronous, robust integrations combine callbacks or polling with pagination, status handling, and reconciliation.
Yes. Martini can consume Rossum’s REST API, submit supported document files, retrieve annotations and source content, receive supported callback notifications, and orchestrate downstream validation and application updates. A dedicated native Martini connector was not verified in the supplied research.
No. A dedicated Rossum connector is not required. Martini can use Rossum’s confirmed native integration mechanisms, including token-authenticated REST APIs, supported callback or hook endpoints, file submission, pagination, and asynchronous processing patterns.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Rossum. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Rossum, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
Use the Rossum REST API as the primary mechanism for document, annotation, queue, schema, and configuration operations. Use selected callback or hook events where they cover the required lifecycle transition, and retain scheduled polling or reconciliation for asynchronous processing and missed notifications. Rossum GraphQL and SOAP APIs were not confirmed.
Rossum supports hook- and callback-based notifications for selected processing events, such as annotation or document status transitions, but coverage is not universal. Confirm the event, payload, retry behavior, and approval semantics for the tenant. Martini can receive the notification, acknowledge quickly, and retrieve the current Rossum resource in a workflow.
Treat upload, extraction, human review, approval, rejection, and export as separate states. Store Rossum and source-system identifiers, use callbacks where supported, poll with bounded intervals when necessary, and run scheduled reconciliation for missed or delayed events. Before writing downstream data, retrieve the latest annotation and apply an idempotency check.
Martini can map nested annotations and line items into canonical and target-specific models, validate required fields, and apply business rules for approval, rejection, and duplicate prevention. Workflows can distinguish authentication, validation, rate-limit, transient, and permanent errors, use bounded retries with backoff, and record correlation IDs, retry counts, and target responses.
Related Martini documentation
Workflows
Connect Rossum with your enterprise systems
Use Martini to orchestrate Rossum document processing, callbacks, annotation mapping, validation, and reliable delivery to downstream applications.