Data Models

The Rossum API SDK provides type-safe dataclass models for all API resources. These models are automatically populated from API responses and provide clear type hints for all fields.

Overview

All models are Python dataclasses with full type annotations. They represent the structure of data returned by the Rossum API and can also be used when sending data to the API.

Key features:

  • Type-safe with full type hints

  • Automatic deserialization from API responses

  • Possibility to use a custom deserializer

  • Support for nested objects

  • Optional fields with sensible defaults

  • Direct mapping to API documentation

Models

Annotation

class rossum_api.models.annotation.Annotation(url, status, schema, modifier, content, id=None, queue=None, creator=None, created_at=None, rir_poll_id=None, email=None, email_thread=None, has_email_thread_with_replies=False, has_email_thread_with_new_replies=False, suggested_edit=None, messages=None, time_spent=0, relations=<factory>, pages=<factory>, document=None, confirmed_at=None, modified_at=None, exported_at=None, arrived_at=None, assigned_at=None, purged_at=None, rejected_at=None, deleted_at=None, export_failed_at=None, organization=None, metadata=<factory>, automated=False, automation_blocker=None, related_emails=<factory>, automatically_rejected=None, prediction=None, assignees=<factory>, labels=<factory>, restricted_access=None, training_enabled=None, einvoice=None, purged_by=None, rejected_by=None, deleted_by=None, exported_by=None, confirmed_by=None, modified_by=None)[source]

Annotation contains all extracted and verified data related to a document.

Every document belongs to a Queue and is related to the Schema, that defines datapoint types and overall shape of the extracted data.

Parameters:

  • url (str) – URL of the annotation object.

  • status (str) – Current status of the annotation. See Annotation Lifecycle for possible values.

  • schema (str) – URL of the schema object.

  • modifier (str | User | None) – URL of the user object that last modified the annotation.

  • content (list[dict[str, Any]] | str) – URL of the annotation content.

  • id (int | None) – Annotation ID.

  • queue (str | None) – URL of the queue object.

  • creator (str | None) – URL of the user object that created the annotation.

  • created_at (str | None) – Timestamp of when the annotation was created.

  • rir_poll_id (str | None) – Internal extractor processing ID.

  • email (str | None) – URL of the email object associated with the annotation.

  • email_thread (str | None) – URL of the email thread object.

  • has_email_thread_with_replies (bool) – Boolean indicating if the annotation’s email thread has replies.

  • has_email_thread_with_new_replies (bool) – Boolean indicating if the annotation’s email thread has new replies.

  • suggested_edit (str | None) – A suggested edit for the annotation.

  • messages (list[dict] | None) – List of messages associated with the annotation.

  • time_spent (float | None) – Total time spent on the annotation in seconds.

  • relations (list[str]) – List of relations.

  • pages (list[str]) – List of page URLs.

  • document (str | Document | None) – URL of the document object.

  • confirmed_at (str | None) – Timestamp of when the annotation was confirmed.

  • modified_at (str | None) – Timestamp of when the annotation was last modified.

  • exported_at (str | None) – Timestamp of when the annotation was exported.

  • arrived_at (str | None) – Timestamp when the annotation arrived.

  • assigned_at (str | None) – Timestamp of when the annotation was assigned to a user.

  • purged_at (str | None) – Timestamp of when the annotation was purged.

  • rejected_at (str | None) – Timestamp of when the annotation was rejected.

  • deleted_at (str | None) – Timestamp of when the annotation was deleted.

  • export_failed_at (str | None) – Timestamp of when the annotation export failed.

  • organization (str | None) – URL of the organization object.

  • metadata (dict[Any, Any]) – Custom data attached to the annotation.

  • automated (bool) – Indicates if the annotation was processed automatically.

  • automation_blocker (AutomationBlocker | str | None) – URL of the automation blocker object.

  • related_emails (list[str]) – List of related email URLs.

  • automatically_rejected (bool | None) – Indicates if the annotation was automatically rejected.

  • prediction (Prediction | None) – Internal description of prediction source and version.

  • assignees (list[str]) – List of URLs referencing users assigned to this annotation.

  • labels (list[str]) – List of labels associated with this annotation.

  • restricted_access (bool | None) – Indicates if the annotation has restricted access.

  • training_enabled (bool | None) – Indicates if training is enabled for this annotation.

  • einvoice (bool | None) – Indicates if this is an e-invoice annotation.

  • purged_by (str | None) – URL of the user object that purged the annotation.

  • rejected_by (str | None) – URL of the user object that rejected the annotation.

  • deleted_by (str | None) – URL of the user object that deleted the annotation.

  • exported_by (str | None) – URL of the user object that exported the annotation.

  • confirmed_by (str | None) – URL of the user object that confirmed the annotation.

  • modified_by (str | None) – URL of the user object that last modified the annotation.

References

https://elis.rossum.ai/api/docs/#annotation.

AutomationBlocker

class rossum_api.models.automation_blocker.AutomationBlocker(id, url, annotation, content=<factory>)[source]

Automation blocker stores reason why Annotation was not automated.

Parameters:

References

https://elis.rossum.ai/api/docs/#automation-blocker.

AutomationBlockerContent

class rossum_api.models.automation_blocker.AutomationBlockerContent(level, type, schema_id=None, samples_truncated=False, samples=<factory>, details=<factory>)[source]

Description of a single reason why Annotation was not automated.

Parameters:

  • level (str) – Whether automation blocker relates to specific datapoint or to the whole Annotation.

  • type (Literal['automation_disabled', 'is_duplicate', 'suggested_edit_present', 'low_score', 'failed_checks', 'no_validation_sources', 'error_message', 'delete_recommendation_filename', 'delete_recommendation_page_count', 'delete_recommendation_field', 'extension']) – The type of automation blocker.

  • schema_id (str | None) – The schema ID associated with this blocker. Only for datapoint level objects.

  • samples_truncated (bool | None) – Indicates if the samples list has been truncated.

  • samples (list[dict[str, Any]]) – Whether number samples were truncated to 10, or contains all of them.

  • details (dict[str, Any]) – Only for level: annotation with type: error_message. Contains message_content with list of error messages.

References

https://elis.rossum.ai/api/docs/#automation-blocker.

Connector

class rossum_api.models.connector.Connector(id, name, url, service_url, params, client_ssl_certificate, authorization_token, client_ssl_key=None, queues=<factory>, authorization_type='secret_key', asynchronous=True, metadata=<factory>)[source]

Connector is used to configure external or internal endpoint of such an extension service.

Connector is an extension of Rossum that allows to validate and modify data during validation and also export data to an external system.

Parameters:

  • id (int) – ID of the connector.

  • name (str) – Name of the connector.

  • url (str) – URL of the connector.

  • service_url (str) – URL of the connector endpoint.

  • params (str | None) – Query params appended to the service_url.

  • client_ssl_certificate (str | None) – Client SSL certificate used to authenticate requests. Must be PEM encoded.

  • authorization_token (str | None) – Token sent to connector in Authorization header to ensure connector was contacted by Rossum.

  • client_ssl_key (str | None) – Client SSL key (write only). Must be PEM encoded. Key may not be encrypted.

  • queues (list[str]) – List of Queue objects that use connector object.

  • authorization_type (str) – Token sent to connector in Authorization header to ensure connector was contacted by Rossum.

  • asynchronous (bool) – Affects exporting: when True, confirm endpoint returns immediately and connector’s save endpoint is called asynchronously later on.

  • metadata (dict[str, Any]) – Client data.

References

https://elis.rossum.ai/api/docs/#connector

Document

class rossum_api.models.document.Document(id, url, s3_name, parent, email, mime_type, creator, created_at, arrived_at, original_file_name, content, metadata=<factory>, annotations=<factory>, attachment_status=None)[source]

Document contains information about one input file.

Parameters:

  • id (int) – ID of the document.

  • url (str) – URL of the document.

  • s3_name (str) – Internal name of object name in S3.

  • parent (str | None) – URL of the parent document (e.g. the zip file it was extracted from).

  • email (str | None) – URL of the email object that document was imported by (only for documents imported by email).

  • mime_type (str) – MIME type of the document, e.g. application/pdf.

  • creator (str | None) – URL of User that created the annotation.

  • created_at (str) – Timestamp of document upload or incoming email attachment extraction.

  • arrived_at (str) – Deprecated. See created_at.

  • original_file_name (str) – File name of the attachment or upload.

  • content (str) – Link to the document’s raw content (e.g. PDF file). May be null if there is no file associated.

  • metadata (dict[str, Any]) – Client data.

  • annotations (list[str]) – List of URLs of Annotation objects related to the document. Usually there is only one annotation.

  • attachment_status (str | None) – Reason, why the document got filtered out on Email ingestion. See attachment status

References

https://elis.rossum.ai/api/docs/#document

DocumentRelation

class rossum_api.models.document_relation.DocumentRelation(id, type, annotation, key, documents, url)[source]

Document relation introduces additional relations between annotations and documents.

Warning

Please note that Document Relation object and all endpoints associated with it are in beta version right now. The API may change in the future.

An Annotation can be related to one or more Document objects and it may belong to several such relations of different types at the same time. These are additional to the main relation between the Annotation and the Document from which it was created.

Parameters:

  • id (int) – ID of the document relation.

  • type (DocumentRelationType) – Type of relationship. Possible values are 'export', 'einvoice'.

  • annotation (str) – URL of related Annotation.

  • key (str | None) – Key used to distinguish several relationships of the same type.

  • documents (list[str]) – List of URLs of related Documnets.

  • url (str) – URL of the relation.

Notes

The combination of type, key and annotation attribute values must be unique.

References

https://elis.rossum.ai/api/docs/#document-relation

class rossum_api.models.email.Email(id, url, queue, inbox, parent, email_thread, children, documents, created_at=None, last_thread_email_created_at=None, subject=None, from_=<factory>, to=<factory>, cc=<factory>, bcc=<factory>, body_text_plain=None, body_text_html=None, metadata=<factory>, type=None, annotation_counts=<factory>, annotations=<factory>, related_annotations=<factory>, related_documents=<factory>, creator=None, filtered_out_document_count=None, labels=<factory>, content=None)[source]

Bases: object

Email represents emails sent to Rossum inboxes.

Parameters:

  • id (int) – ID of the email.

  • url (str) – URL of the email.

  • queue (str) – URL of the associated Queue.

  • inbox (str) – URL of the associated Inbox.

  • parent (str | None) – URL of the parent email.

  • email_thread (str | None) – URL of the associated email thread.

  • children (list[str]) – List of URLs of the children emails.

  • documents (list[str]) – List of URLs of Document objects attached to the email.

  • created_at (str | None) – Timestamp of incoming email.

  • last_thread_email_created_at (str | None) – (Deprecated) Timestamp of the most recent email in this email thread.

  • subject (str | None)

  • from – Information about sender containing keys email and name.

  • to (list[dict[str, Any]]) – List that contains information about recipients.

  • cc (list[dict[str, Any]]) – List that contains information about recipients of carbon copy.

  • bcc (list[dict[str, Any]]) – List that contains information about recipients of blind carbon copy.

  • body_text_plain (str | None) – Plain text email section (shortened to 4kB).

  • body_text_html (str | None) – HTML email section (shortened to 4kB).

  • metadata (dict[str, Any]) – Client data.

  • type (EmailType | None) – Email type. Can be incoming or outgoing.

  • annotation_counts (dict[str, Any]) – Information about how many annotations were extracted from email attachments and in which state they currently are. This attribute is intended for INTERNAL use only and may be changed in the future.

  • annotations (list[str]) – List of URLs of Annotation objects that arrived via email

  • related_annotations (list[str]) – List of URLs of Annotation objects that are related to the email (e.g. rejected by that, added as attachment etc.).

  • related_documents (list[str]) – List of URLs of Document objects related to the email, (e.g. by forwarding email containing document as attachment etc.).

  • creator (str | None) – User that have sent the email. None if email has been received via SMTP.

  • filtered_out_document_count (int | None) – Number of documents automatically filtered out by Rossum smart inbox. This attribute is intended for INTERNAL use only and may be changed in the future.

  • labels (list[Literal['rejection', 'automatic_rejection', 'rejected', 'automatic_status_changed_info', 'forwarded', 'reply']]) – List of email labels.

  • content (str | None) – URL of the emails content.

References

https://elis.rossum.ai/api/docs/#email

EmailTemplate

class rossum_api.models.email_template.EmailTemplate(id, name, url, queue, organization, subject, message, type, enabled, automate, triggers=<factory>, to=<factory>, cc=<factory>, bcc=<factory>)[source]

Email template represents templates one can choose from when sending an email from Rossum.

Parameters:

  • id (int) – ID of the email template.

  • name (str) – Name of the email template.

  • url (str) – URL of the email template.

  • queue (str) – URL of the associated Queue.

  • organization (str) – URL of the associated Organization.

  • subject (str) – Email subject.

  • message (str) – Name of the email template.

  • type (Literal['rejection', 'rejection_default', 'email_with_no_processable_attachments', 'custom']) – Type of the email template.

  • enabled (bool) – (Deprecated). Use automate instead.

  • automate (bool) – True if user wants to send email automatically on the action, see type.

  • triggers (list[str]) – URLs of the linked triggers. Read more about triggers.

  • to (list[dict[str, Any]]) – List that contains information about recipients.

  • cc (list[dict[str, Any]]) – List that contains information about recipients of carbon copy.

  • bcc (list[dict[str, Any]]) – List that contains information about recipients of blind carbon copy.

References

https://elis.rossum.ai/api/docs/#email-template.

https://elis.rossum.ai/api/docs/#using-triggers.

Hook

class rossum_api.models.hook.Hook(id, name, url, active, config, test, guide, read_more_url, extension_image_url, type='webhook', metadata=<factory>, queues=<factory>, run_after=<factory>, events=<factory>, settings=<factory>, settings_schema=None, secrets=<factory>, extension_source='custom', sideload=<factory>, token_owner=None, token_lifetime_s=None, description=None)[source]

Hook is an extension of Rossum that is notified when specific event occurs.

Hook object is used to configure what endpoint or function is executed and when. For an overview of other extension options see Extensions.

Notes

Hooks are notified in parallel if run_after is not specified.

Parameters:

  • id (int) – ID of the hook.

  • name (str) – Name of the hook.

  • url (str) – URL of the hook.

  • active (bool) – If set to True the hook is notified.

  • config (dict[str, Any]) – Configuration of the hook.

  • test (dict[str, Any]) – Input saved for hook testing purposes, see Test a hook.

  • guide (str | None) – Description how to use the extension.

  • read_more_url (str | None) – URL address leading to more info page.

  • extension_image_url (str | None) – URL address of extension picture.

  • type (Literal['webhook', 'function']) – type of the hook.

  • metadata (dict[str, Any]) – Client data

  • queues (list[str]) – List of Queue objects that use hook object.

  • run_after (list[str]) – List of all hooks that has to be executed before running this hook.

  • events (list[str]) – List of events, when the hook should be notified. For the list of events see Webhook events.

  • settings (dict[str, Any]) – Specific settings that will be included in the payload when executing the hook. Field is validated with json schema stored in settings_schema field.

  • settings_schema (dict[str, Any] | None) – [BETA] JSON schema for settings field validation.

  • secrets (dict[str, Any]) – JSON schema for settings field validation. This is in BETA.

  • extension_source (str) – Import source of the extension.

  • sideload (list[str]) –

    List of related objects that should be included in hook request. For the list of events see Webhook events.

  • token_owner (str | None) – URL of a User. If present, an API access token is generated for this user and sent to the hook. Users with organization group admin cannot be set as token_owner. If None, token is not generated.

  • token_lifetime_s (int | None) – Lifetime number of seconds for rossum_authorization_token (min=0, max=7200). This setting will ensure the token will be valid after hook response is returned. If None, default lifetime of 600 is used.

  • description (str | None) – Hook description text.

References

https://elis.rossum.ai/api/docs/#hook

https://elis.rossum.ai/api/docs/#test-a-hook

https://elis.rossum.ai/api/docs/#webhook-events

Inbox

class rossum_api.models.inbox.Inbox(id, name, url, queues, email, email_prefix, bounce_email_to, bounce_unprocessable_attachments=False, bounce_postponed_annotations=False, bounce_deleted_annotations=False, bounce_email_with_no_attachments=True, metadata=<factory>, filters=<factory>, dmarc_check_action='accept')[source]

Inbox enables email ingestion to a related Queue.

We enforce email domain to match Rossum domain (e.g. .rossum.app). email_prefix may be used to construct unique email address.

Parameters:

  • id (int) – ID of the inbox.

  • name (str) – Name of the inbox.

  • url (str) – URL of the inbox.

  • queues (list[str]) – Queue that receives documents from inbox. Queue has to be passed in list due to backward compatibility. It is possible to have only one queue per inbox.

  • email (str) – Rossum email address (e.g. east-west-trading-co-a34f3a@<example>.rossum.app)

  • email_prefix (str) – Rossum email address prefix (e.g. east-west-trading-co). Maximum length allowed is 57 chars.

  • bounce_email_to (str | None) – (Deprecated) Email address to send notifications to (e.g. about failed import). Configuration moved to Email notifications settings.

  • bounce_unprocessable_attachments (bool) –

    (Deprecated) Whether return back unprocessable attachments (e.g. MS Word docx) or just silently ignore them. When true, minimum image size requirement does not apply. Configuration moved to Email notifications settings.

  • bounce_postponed_annotations (bool) –

    (Deprecated) Whether to send notification when annotation is postponed. Configuration moved to Email notifications settings.

  • bounce_deleted_annotations (bool) –

    (Deprecated) Whether to send notification when annotation is deleted. Configuration moved to Email notifications settings.

  • bounce_email_with_no_attachments (bool) –

    (Deprecated) Whether to send notification when no processable documents were found. Configuration moved to Email notifications settings.

  • metadata (dict[str, Any]) – Client data.

  • filters (dict[str, Any])

  • dmarc_check_action (Literal['accept', 'drop']) – Decides what to do with incoming emails, that don’t pass the DMARC check.

References

https://elis.rossum.ai/api/docs/#inbox

https://elis.rossum.ai/api/docs/#email-notification-settings

Organization

class rossum_api.models.organization.Organization(id, name, url, workspaces, users, organization_group, is_trial, created_at, trial_expires_at=None, expires_at=None, oidc_provider=None, ui_settings=<factory>, metadata=<factory>)[source]

Organization is a basic unit that contains all objects that are required to fully use Rossum platform.

Warning

Please note that Organization is an internal API and can be changed without notice.

Parameters:

  • id (int) – ID of the organization.

  • name (str) – Name of the organization.

  • url (str) – URL of the organization.

  • workspaces (list[str]) – List of Workspace objects in the organization.

  • users (list[str]) – List of User in the organization.

  • organization_group (str) – URL to organization group the organization belongs to.

  • is_trial (bool) – Property indicates whether this license is a trial license.

  • created_at (str) – Timestamp for when the organization was created.

  • trial_expires_at (str | None) – Timestamp for when the trial period ended (ISO 8601).

  • expires_at (str | None) – Timestamp for when the organization is to be expired.

  • oidc_provider (str | None) – (Deprecated) OpenID Connect provider name.

  • ui_settings (dict) – Organization-wide frontend UI settings (e.g. locales). Rossum internal.

  • metadata (dict) – Client data.

References

https://elis.rossum.ai/api/docs/#organization

Queue

class rossum_api.models.queue.Queue(id, name, url, workspace, connector, schema, inbox, counts, session_timeout='01:00:00', webhooks=<factory>, hooks=<factory>, users=<factory>, rir_url=None, rir_params=None, automation_enabled=False, automation_level='never', default_score_threshold=0.8, locale='en_GB', metadata=<factory>, settings=<factory>, dedicated_engine=None, generic_engine=None, use_confirmed_state=False, document_lifetime=None, delete_after=None, status=None, engine=None, training_enabled=True)[source]

Queue represents a document processing queue in Rossum.

A queue defines the document processing workflow and connects documents to their extraction schema, processing inbox, and user groups.

Parameters:

  • id (int) – Id of the queue.

  • name (str) – Name of the queue (max. 255 characters).

  • url (str) – URL of the queue.

  • workspace (str | None) – Workspace in which the queue should be placed (it can be set to null, but bear in mind that it will make the queue invisible in the Rossum UI and it may cause some unexpected consequences).

  • connector (str | None) – Connector associated with the queue.

  • schema (str) – Schema which will be applied to annotations in this queue.

  • inbox (str | None) – Inbox for import to this queue.

  • counts (dict[str, int]) – Count of annotations per status.

  • session_timeout (str) – Time before annotation will be returned from reviewing status to to_review (timeout is evaluated every 10 minutes). Defaults to 1 hour.

  • webhooks (list[str]) – (Deprecated) Webhooks associated with the queue (serves as an alias for hooks attribute).

  • hooks (list[str]) – Hooks associated with the queue.

  • users (list[str]) – Users associated with this queue.

  • rir_url (str | None) – (Deprecated) Use generic_engine or dedicated_engine to set AI Core Engine.

  • rir_params (str | None) – URL parameters to be passed to the AI Core Engine.

  • automation_enabled (bool) – Toggle for switching automation on/off.

  • automation_level (str) – Set level of automation.

  • default_score_threshold (float) – Threshold used to automatically validate field content based on AI confidence scores.

  • locale (str) – Typical originating region of documents processed in this queue specified in the locale format. If auto option is chosen, the locale will be detected automatically if the organization group has access to Aurora engine. Otherwise, default option (en_GB) will be used.

  • metadata (dict[str, Any]) – Client data.

  • settings (dict[str, Any]) – Queue UI settings.

  • dedicated_engine (str | dict[str, Any] | None) – Dedicated engine used for processing documents uploaded to this queue. If dedicated_engine is set generic_engine must be null.

  • generic_engine (str | dict[str, Any] | None) – Generic engine used for processing documents uploaded to this queue. If generic_engine is set dedicated_engine must be null. If both engines are null, a default generic one gets set.

  • use_confirmed_state (bool) – Affects exporting: when true, confirm endpoint transitions annotation to confirmed status instead to exporting.

  • document_lifetime (str | None) – Data retention period – annotations will be automatically purged this time after their creation. The format of the value is ‘[DD] [HH:[MM:]]ss[.uuuuuu]’, e.g. 90 days retention can be set as ‘90 00:00:00’. Please keep in mind that purging documents in Rossum can limit its learning capabilities.

  • delete_after (str | None) – For internal use only (When a queue is marked for its deletion it will be done after this date).

  • status (str | None) – Current status of the queue.

  • engine (str | None) – Engine associated with the queue.

  • training_enabled (bool) – Indicates if training is enabled for this queue.

References

https://elis.rossum.ai/api/docs/#queue.

Relation

class rossum_api.models.relation.Relation(id, type, key, parent, annotations, url)[source]

Relation introduces common relations between annotations.

An Annotation can be related to one or more other annotations and it may belong to several relations at the same time.

Parameters:

  • id (int) – ID of the relation.

  • type (RelationType) – Type of relationship. Possible values are 'edit', 'attachment', 'duplicate'.

  • key (str | None) – Key used to distinguish several instances of the same type.

  • parent (str | None) – URL of the parent Annotation in case of 1-M relationship.

  • annotations (list[str]) – List of URLs of related Annotation objects.

  • url (str) – URL of the relation.

References

https://elis.rossum.ai/api/docs/#relation

RelationType

class rossum_api.models.relation.RelationType(value)[source]

Type of relationship between annotations.

EDIT

Created after editing annotation in user interface (rotation or split of the document). The original annotation is set to parent attribute and newly created annotations are set to annotations attribute.

ATTACHMENT

Represents the state that one or more documents are attachments to another document. key is null in this case. Feature must be enabled.

DUPLICATE

Created after importing the same document that already exists in Rossum for current organization. If duplicate relation already exists then corresponding annotation is added to existing relation. key is set to MD5 hash of document content.

Rule

class rossum_api.models.rule.Rule(id, name, enabled, organization, schema=None, trigger_condition='True', url=None, created_by=None, created_at=None, modified_by=None, modified_at=None, rule_template=None, synchronized_from_template=False, actions=<factory>)[source]

Rule object represents arbitrary business rules added to schema objects.

Rules allow you to define custom business logic that is evaluated when specific conditions are met. Each rule consists of a trigger condition (TxScript formula) and a list of actions to execute when the condition evaluates to True.

Warning

Rules are currently in beta version and the API may change. Talk with a Rossum representative about enabling this feature.

Notes

The trigger condition is a TxScript formula which controls the execution of actions. There are two evaluation modes:

  • Simple mode: when the condition does not reference any datapoint, or only references header fields. Example: len(field.document_id) < 10.

  • Line-item mode: when the condition references a line item datapoint (a column of a multivalue table). Example: field.item_amount > 100.0.

In line item mode, the condition is evaluated once for each row of the table.

Parameters:

  • id (int) – Rule object ID.

  • url (str | None) – Rule object URL.

  • name (str) – Name of the rule.

  • enabled (bool) – If False the rule is disabled (default: True).

  • organization (str) – URL of the Organization the rule belongs to.

  • schema (str | None) – URL of the Schema the rule belongs to.

  • trigger_condition (str) – A condition for triggering the rule’s actions. This is a formula evaluated by Rossum TxScript. Note that trigger condition must evaluate strictly to "True", truthy values are not enough to trigger the execution of actions. Wrap your condition with bool(your_condition) if necessary.

  • created_by (str | None) – URL of the User who created the rule.

  • created_at (str | None) – Timestamp of the rule creation.

  • modified_by (str | None) – URL of the User who was the last to modify the rule.

  • modified_at (str | None) – Timestamp of the latest modification.

  • rule_template (str | None) – URL of the rule template the rule was created from.

  • synchronized_from_template (bool) – Signals whether the rule is automatically updated from the linked template.

  • actions (list[RuleAction]) – List of RuleAction objects. See Rule actions.

References

https://elis.rossum.ai/api/docs/#rule

RuleAction

class rossum_api.models.rule.RuleAction(id, type, payload, event, enabled=True)[source]

Rule action object defines actions to be executed when trigger condition is met.

Parameters:

  • id (str) – Rule action ID. Needs to be unique within the Rule’s actions.

  • enabled (bool) – If False the action is disabled (default: True).

  • type (str) –

    Type of action. See Rule actions for the list of possible actions.

  • payload (dict[str, Any]) –

    Action payload. Structure depends on the action type. See Rule actions for details.

  • event (str) – Actions are configured to be executed on a specific event. See Trigger events.

References

https://elis.rossum.ai/api/docs/#rule-actions

Schema

class rossum_api.models.schema.Schema(id, name=None, queues=<factory>, url=None, content=<factory>, metadata=<factory>, modified_by=None, modified_at=None)[source]

Schema specifies the set of datapoints that are extracted from the document.

For more information see Document Schema.

Parameters:

  • id (int) – ID of the schema.

  • name (str | None) – Name of the schema.

  • queues (list[str]) – List of Queue objects that use schema object.

  • url (str | None) – URL of the schema.

  • content (list[Section]) –

    List of sections (top-level schema objects, see Document Schema for description of schema).

  • metadata (dict) – Client data.

References

https://elis.rossum.ai/api/docs/#schema.

https://elis.rossum.ai/api/docs/#document-schema.

Section

class rossum_api.models.schema.Section(id, children=<factory>, category='section', label=None, icon=None)[source]

Top-level container grouping related datapoints, multivalues, and tuples.

Parameters:

  • id (str) – Unique identifier for the section.

  • children (list[Datapoint | Multivalue | Tuple]) – List of datapoints, multivalues, and tuples belonging to this section.

  • category (str) – Category of the object, always “section”.

  • label (str | None) – Display label for the section.

  • icon (str | None) – Icon identifier for the section.

References

https://elis.rossum.ai/api/docs/#section.

https://elis.rossum.ai/api/docs/#document-schema.

Datapoint

class rossum_api.models.schema.Datapoint(id, type=None, label=None, description=None, category='datapoint', disable_prediction=False, hidden=False, can_export=True, can_collapse=False, rir_field_names=None, default_value=None, constraints=<factory>, score_threshold=None, options=None, ui_configuration=None, width=None, stretch=False, width_chars=None, formula=None, prompt=None, context=None)[source]

A datapoint represents a single value, typically a field of a document or global document information.

Parameters:

  • id (str) – Unique identifier for the datapoint.

  • type (Optional[Literal['string', 'number', 'date', 'enum', 'button']]) – Data type of the object

  • label (str | None) – Display label for the datapoint.

  • description (str | None) – Description of the datapoint.

  • category (str) – Category of the object, always “datapoint”.

  • disable_prediction (bool) – If True, AI predictions are disabled for this field.

  • hidden (bool) – If True, the field is hidden in the UI.

  • can_export (bool) – If False, datapoint is not exported through export endpoint.

  • can_collapse (bool) – If True, tabular (multivalue-tuple) datapoint may be collapsed in the UI.

  • rir_field_names (list[str] | None) – List of references used to initialize object value from AI engine predictions.

  • default_value (str | None) – Default value used when AI engine does not return any data or rir_field_names are not specified.

  • constraints (dict) – Map of various constraints for the field.

  • score_threshold (float | None) – Threshold (0-1) used to automatically validate field content based on AI confidence scores. If not set, queue.default_score_threshold is used.

  • options (list[dict] | None) – List of available options for enum type fields.

  • ui_configuration (dict | None) – Settings affecting behavior of the field in the application.

  • width (int | None) – Width of the column in characters. Only supported for table datapoints.

  • stretch (bool) – If True, column will expand proportionally when total width doesn’t fill screen. Only supported for table datapoints.

  • width_chars (int | None) – Deprecated. Use width and stretch instead.

  • formula (str | None) – Formula definition, required only for fields of type formula. rir_field_names should be empty.

  • prompt (str | None) – Prompt definition, required only for fields of type reasoning.

  • context (list[str] | None) – Context information for the field.

References

https://elis.rossum.ai/api/docs/#datapoin.

https://elis.rossum.ai/api/docs/#document-schema.

Multivalue

class rossum_api.models.schema.Multivalue(id, children, category='multivalue', label=None, rir_field_names=None, min_occurrences=None, max_occurrences=None, grid=None, show_grid_by_default=False, hidden=False)[source]

Multivalue is list of datapoints or tuples of the same type.

Represents a container for data with multiple occurrences (such as line items) and can contain only objects with the same id.

Parameters:

  • id (str) – Unique identifier for the multivalue.

  • children (Datapoint | Tuple) – Object specifying type of children. Can contain only objects with categories tuple or datapoint.

  • category (str) – Category of the object, always “multivalue”.

  • label (str | None) – Display label for the multivalue.

  • rir_field_names (list[str] | None) – List of names used to initialize content from AI engine predictions. If specified, the value of the first field from the array is used, otherwise default name line_items is used. Can be set only for multivalue containing objects with category tuple.

  • min_occurrences (int | None) – Minimum number of occurrences of nested objects. If violated, fields should be manually reviewed.

  • max_occurrences (int | None) – Maximum number of occurrences of nested objects. Additional rows above this limit are removed by extraction process.

  • grid (dict | None) – Configure magic-grid feature properties.

  • show_grid_by_default (bool) – If True, the magic-grid is opened instead of footer upon entering the multivalue. Applied only in UI.

References

https://elis.rossum.ai/api/docs/#multivalue.

https://elis.rossum.ai/api/docs/#document-schema.

Tuple

class rossum_api.models.schema.Tuple(id, children, category='tuple', label=None, disable_prediction=False, hidden=False, rir_field_names=None)[source]

Container representing one line of tabular data.

A tuple must be nested within a multivalue object, but unlike multivalue, it may consist of objects with different ids.

Parameters:

  • id (str) – Unique identifier for the tuple.

  • children (list[Datapoint]) – Array specifying objects that belong to a given tuple.

  • category (str) – Category of the object, always “tuple”.

  • label (str | None) – Display label for the tuple.

  • disable_prediction (bool) – If True, AI predictions are disabled for this tuple.

  • hidden (bool) – If True, the tuple is hidden in the UI.

  • rir_field_names (list[str] | None) – List of names used to initialize content from AI engine predictions. If specified, the value of the first extracted field is used, otherwise no AI engine initialization is done.

References

https://elis.rossum.ai/api/docs/#tuple.

https://elis.rossum.ai/api/docs/#document-schema.

Task

class rossum_api.models.task.Task(id, url, type, status, expires_at, content=None, detail=None, code=None, result_url=None)[source]

Tasks are used as status monitors of asynchronous operations.

Tasks with succeeded status can redirect to the object created as a result of them. If no_redirect=true is passed as a query parameter, endpoint won’t redirect to an object created, but will return information about the task itself instead.

Warning

Please note that task object and all endpoints associated with it are in beta version right now. The API may change in the future.

Parameters:

  • id (int) – ID of task object.

  • url (str) – URL of task object.

  • type (TaskType) – Currently supported options for task types are documents_download, upload_created, and email_imported.

  • status (TaskStatus) – One of running, succeeded or failed.

  • expires_at (str) – Timestamp of a guaranteed availability of the task object. Expired tasks are being deleted periodically.

  • content (dict[str, Any] | None) – Detailed information related to tasks (see tasks content detail).

  • detail (str | None) – Detailed message on the status of the task. For failed tasks, error id is included in the message and can be used in communication with Rossum support for further investigation.

  • code (str | None) – Error code.

  • result_url (str | None) – Succeeded status resulting redirect URL.

References

https://elis.rossum.ai/api/docs/#task.

Upload

class rossum_api.models.upload.Upload(id, url, queue, organization, creator, created_at, documents, additional_documents=<factory>, annotations=<factory>, email=None)[source]

Represent an upload.

Parameters:

  • id (int) – ID of upload object.

  • url (str) – URL of upload object.

  • queue (str) – URL of the target Queue of the upload.

  • organization (str) – URL of related Organization.

  • creator (str) – URL of the User who created the upload.

  • created_at (str) – Time of the creation of the upload.

  • documents (list[str]) – URLs of the uploaded Document.

  • additional_documents (list[str]) – URLs of additional Document created in upload.created event hooks.

  • annotations (list[str]) – URLs of all created Annotation.

  • email (str | None) – URL of the Email that created the upload object.

References

https://elis.rossum.ai/api/docs/#upload.

User

class rossum_api.models.user.User(id, url, first_name, last_name, email, date_joined, username, organization, last_login=None, is_active=True, email_verified=False, password=None, groups=<factory>, queues=<factory>, ui_settings=<factory>, metadata=<factory>, oidc_id=None, auth_type='password', deleted=False)[source]

User represents individual user of Rossum.

Every user is assigned to an organization and can have access to multiple queues and user groups for document processing workflows.

Parameters:

  • id (int) – Id of the user.

  • url (str) – URL of the user.

  • first_name (str) – First name of the user.

  • last_name (str) – Last name of the user.

  • email (str) – Email of the user.

  • date_joined (str) – Date of user join.

  • username (str) – Username of a user.

  • organization (str) – Related organization.

  • last_login (str | None) – Date of last login.

  • is_active (bool) – Whether user is enabled or disabled.

  • email_verified (bool | None) – Whether the user’s email is verified.

  • password (str | None) – Password (not shown on API).

  • groups (list[str]) – List of user role (permission groups).

  • queues (list[str]) – List of queues user is assigned to.

  • ui_settings (dict) – User-related frontend UI settings (e.g. locales). Rossum internal.

  • metadata (dict) – Client data.

  • oidc_id (str | None) – OIDC provider id used to match Rossum user (displayed only to admin user).

  • auth_type (str) – Authorization method, can be sso or password. This field can be edited only by admin.

  • deleted (bool) – Whether a user is deleted.

References

https://elis.rossum.ai/api/docs/#user

Workspace

class rossum_api.models.workspace.Workspace(id, name, url, autopilot, organization, queues=<factory>, metadata=<factory>)[source]

Workspace is a container of :class:`~rossum_api.models.queue.Queue.

Parameters:

  • id (int) – ID of the workspace.

  • name (str) – Name of the workspace.

  • url (str) – URL of the workspace.

  • autopilot (bool) – (Deprecated) Whether to automatically confirm datapoints (hide eyes) from previously seen annotations

  • organization (str) – URL of the related :class:`~rossum_api.models.organization.Organization.

  • queues (list[str]) – List of :class:`~rossum_api.models.queue.Queue that belong to the workspace.

  • metadata (dict[str, Any]) – Client data.

Notes

Please note that autopilot configuration has been moved to :class:`~rossum_api.models.queue.Queue. Option autopilot remains read-only on Workspace and represents autopilot configuration set to :class:`~rossum_api.models.queue.Queue within a workspace.

References

https://elis.rossum.ai/api/docs/#workspace

Model Usage Examples

Creating Model Instances

Models can be created manually or are automatically deserialized from API responses:

from rossum_api.models.workspace import Workspace

# Automatically deserialized from API
workspace = await client.retrieve_workspace(123)
print(workspace.name, workspace.id)

# Manual creation (for testing)
workspace = Workspace(
    id=123,
    name="My Workspace",
    url="https://elis.rossum.ai/api/v1/workspaces/123",
    organization="https://elis.rossum.ai/api/v1/organizations/1",
    autopilot=False,
)

Accessing Nested Objects

Some models contain references to other models:

# Annotation can have a nested Document object
annotation = await client.retrieve_annotation(456)

# If document is expanded in the API response
if isinstance(annotation.document, Document):
    print(f"Document: {annotation.document.original_file_name}")
# Otherwise it's just a URL string
else:
    print(f"Document URL: {annotation.document}")

Working with Enums

Models use Python enums for fields with fixed values:

from rossum_api.models.document_relation import DocumentRelationType

# Check relation type
if relation.type == DocumentRelationType.EXPORT:
    print("This is an export relation")

Type Hints

All models have full type hints for IDE autocomplete and type checking:

def process_annotation(annotation: Annotation) -> None:
    # IDE will provide autocomplete for annotation fields
    print(annotation.status)
    print(annotation.content)

    # Type checker will catch errors
    # annotation.nonexistent_field  # Error: Annotation has no attribute 'nonexistent_field'

See Also