Iris by Roots Automation – API Documentation
Introduction
The Iris platform provides users access to state-of-the-art intelligent document processing and our patented human in the loop QA system. The Platform is designed to best operate integrated into an automated document management process. However, we do provide a manual upload option through the user interface for testing and small-batch purposes.
Incoming APIs
The following APIs are currently available for all customers:
API
Description
Example Call: Upload Document
Content-Type : application/json
Body:
upload – your image file
details – JSON formatted string
- api_key – string – project-level authentication code
- project_id – integer – project-level identification
- Package_name – string – (optional) – user defined field for tracking documents; typically using either a Unique Document ID or File Name
Postman Example: Below is a screenshot from an example API call using the Postman API tool. Note this embedded URL in the below screenshot: https://upload.iris.rootsautomation.com
- 200 Response: JSON response upon successful completion of file upload
"intake_session_id": "4ee215f1-76e1-493d-8f0d-f16b3dd5dff6",
"package_name": "postmen_sample_file",
"status": "processing",
"package_id": "2811"
}
- Sample Error Response
"intake_session_id": "6f9049fe-c05a-407c-8631-ffeaceb1aeb8",
"package_name": "",
"status": "failure",
"error": "Could not process a file with 0 bytes"
}
Authentication:
Outgoing APIs:
Overview:
API
Description
Example Call: Upload Document
Content-Type: application/json
Params:
package_id– integer – the id of the package being requested
api_key – string – project-levelauthentication code
Postman Example: Below is a screenshot from an example API call using the Postman API tool. Note this embedded URL in the below screenshot: https://iris.rootsautomation.com/api/collector?package_id={{pckg_id}}&api_key={{api_key}}
- 200 Response: JSON response upon successful completion of file upload
"status": "complete",
"extracted_data": [
{
"file": "CMS-1500default",
"field_name": "1 - All",
"comment": null,
"error": null,
"field_value": "7"
}
],
"additional_info": [],
"comments": ""
}
- 200 Response: Response when extraction has not completed
"package_id": "34474",
"status": "processing",
"extracted_data": [],
"additional_info": [],
"comments": ""
}
- 401 Unauthorized: Response when the wrong api_key is used to access a package
"package_id": "34474",
"status": "unauthorized",
"extracted_data": [],
"additional_info": [],
"comments": "api_key does not match"
}
- 400 Response: Bad Request
"package_id": "None",
"status": "failed",
"extracted_data": [],
"additional_info": null,
"comments": "'package_id' required inquery params, check query params of request"
}
Authentication:
Webhook
Description
*Note: Endpoints are hosted not by Roots Automation, but bycustomers themselves and therefore the definition of those endpoints isentirely up to the owner/developer. Roots Automation does not provide technicalsupport for systems outside of the Iris platform.
Opening Document Export configuration menu:
Click "Document export" to open.
Screens:
URL– https URL where JSON definition of your form data will be sent
- sample JSON payload:
- <add payload>
Parameters – enter any additional URL parameters to be sent with request
Test – manually send a sample call to test configuration
Headers – enter any headers required by the receiving endpoint
- This sends a ‘blank’ JSON definition in the payload to test incoming data format
Not finding an answer?
Account Creation
Creating your account is the first step to getting started with Iris.
- Click ‘Create Account’
- Enter your Account Name (usually your organization name)
- Create your Iris credentials
- Enter your work email address (this is where your verification link will be sent)
- Enter your name- Choose a password
- Click ‘Create account and user’
Account Login
An email with a verification link will be sent to the email address provided, and you’ll be prompted to log in with your email address and password. At the account login screen, enter the credentials you created and you’re ready to get started!
Account Home Page - Overview
The Account Home Page is the first page you see when you log in to Iris.
If you are an Admin* user, you can:
- view and access all projects in your Account
- create a new project- invite new users to the Account
- view invites sent to users to join the Account
If you are a Team Member user, you can:
- view and access all projects you have access to
Account Home Page - Access Projects & Documents
To access further details for a project:
- Click on the Project Name
- This will re-direct you to the Project Home Page
To check the project type (e.g., if the project is Data Extraction only, Data Extraction & Scoring. or Data Extraction, Scoring & QA):-
The Project Type is indicated below the Project Name, on the Account home page
Account Home Page - Create a New Project
To access further details for a project:
To create a new project:
- Click Create New Project
- Input a name for your project
- Select the project type*
- Click Create
If you want to create another project, click Create another project.
Account Home Page - Invite a New User
Only admin users can invite a new user to join their account.
To invite a new user:
- Click Invite new user
- Enter the new user’s corporate email, first and last name
- Select at least one project they will have access to
- If the new user should be an Account Admin, check the Is Account Admin box.
Project Home Page - Overview
To access further details for a Project, click on the name of the Project in the Account Home page.
Here you will see stats at the top of the page that show you how many forms in your project are in each status (Scoring, QA, and Completed). You can also see the members of your project team and what role they are in.
As an admin or manager user, you can take the following actions from this screen:
- Manage Your Team: change the role of any team member
- Add Documents: upload forms to the project
- Document Export: extract information on completed forms to a defined endpoint for offline review
Project Home Page - Manage Your Team
This screen allows you to manage your team’s responsibilities. You can change a user’sby clicking on the new role and then Save.
Project Home Page – Add Documents
This screen allows you to add documents (i.e. scanned images) to your project. You may drag and drop a file* into the window or use the Browse button to search for the form file on your PC. You may assign an ID number to your document or leave that field blank.
Project Home Page – Document Upload and Export
Admin users have access to the Document Upload and Document Export features.
- Document Upload: This feature allows you to upload multiple documents at once programmatically via API from a specified location on your system.
- Document Export: Once enabled and configured, all forms in a Completed status will be exported programmatically via API to an endpoint on your system.
For more information: API Documentation | Iris by Roots Automation
List of Documents – Filtering and Sorting
Clicking ‘View Documents’ from the Project Home Page will bring you to the List of Forms. Here you will see all documents that have been uploaded to your project, as well as Sort and Filter options.
Sort by: Select whether to sort the forms in order by the date they were created (oldest to newest or newest to oldest) or by the date they were last updated.
Filter by: Show Only – Select an option to view only the forms that are either in an Available or Locked status.
Status: Select 1 or more options to view only the forms that are in a particular status(es): Uploaded, Scoring, QA, Completed, or Failed.
Clear: Clears all the filter and sort settings.
List of Documents – Statuses
There are five possible statuses in the application:
Uploaded: A document is being processed and data is being extracted.
Scoring: Data has been extracted. This is the first human checkpoint. Users with Scoring permissions review the scanned form image and edit extracted data to ensure accurate information.
QA: After Scoring, forms are sent to QA, this is the second human checkpoint. Users with QA permissions review the scanned image and extracted data to ensure no mistakes.
Completed: After QA forms are sent to a Completed status. The extracted data is no longer editable and the form is ready for download.
Failed: The form is not recognizable.
List of Documents – Locking and Unlocking
Iris only allows one user to edit a form at a time. When someone is editing a form, a lock icon will appear to the left of the item in the document list.Admin users may Force Unlock a form by clicking on the lock icon to the left of the locked form, and clicking Force Unlock.
Available means the form is not being worked by anyone.
Locked means a user is viewing the form and it is locked for editing by any other users. If a user does click on a form that is currently open by another user, it will be read-only.
List of Documents – History
Each item in the list contains an audit trail of which users have touched the item and what actions they performed. Clicking on any item in the list displays this information on the right-hand side of the screen.
List of Documents – Download
For Admin and Manager users, forms that are in a Completed status will have a ‘Download’ button to the right of the Document List. This allows you to download a copy of the processed form to your system for offline review. The exported file is in a json format.
Scoring – Selecting a form
In order to begin the Scoring process, select one of the forms that is in a status. Clicking the name of the form on the left-hand side in purple font will take you to the form detail screen or Annotations Page.*
On this screen, you will see atop menu bar, an image of the scanned form, and an editable form on the right-hand side of the screen.
Scoring – Form Detail Screen (Annotations Page)
There are several features at the top of the screen:
Filter: Filter the fields on the right-hand side by the bot’s level of confidence in the accuracy of the data, or by any empty fields
Zoom: Zoom in or out on the form using the scroll bar. Clicking the left-right arrow button fits the form to the width of the window.
X-Ray Mode: When X-Ray Mode is activated, a highlighted box will appear over the scanned image of the form. As you click or tab through the fields in the editable form, the box will move to highlight the fields you are working on.
Scoring – Checking the Digital Coworker's Work
Scoring allows you to check that the bot has correctly extracted the information from the form. You should carefully review each field has been filled out accurately and completely, and no extraneous information appears.*
If any errors are detected, you can make corrections by editing the necessary fields in the editable section on the right-hand side.
You can move to the next field by either clicking on it or using the Tab button on your keyboard. When a field in the editable form is selected, the corresponding section on the scanned form image will be highlighted.
Scoring – Checking the Digital Coworker's Work
As you work down the list of fields, a running count of how many fields have been edited by the Scorer is displayed in the top menu bar. Fields that have been edited will have a ‘pencil’ icon next to them.
Hovering over the pencil will display a pop-up window that shows the original value that was extracted by the bot.
If a user edits a field in error, they can change the value back to the original value. The pencil icon will be removed, and the count of edits made will be updated.
You may use the 'Save' button to save your work at any time.
Once you are confident all the errors have been corrected, click “Submit to QA” to send the form to the next step in the process.*
QA – Checking the Checker
‘QA’ is the second and final stage in the process. Just like in the Scoring stage, users can review the image and edit the extracted data using the editable form.
The QA stage allows users to ‘check the checker’ and review the work of the scorer to ensure no errors in the data extraction were missed.
QA – Performing the QA Review
In order to begin the QA process, select a form that is in a status. Clicking the name of the form on the left-hand side will take you to the form detail screen.
On this screen, you will see a top menu bar, an image of the scanned form, and an editable form on the right-hand side of the screen.
Review the edits made during the Scoring stage and ensure no errors were missed. If any corrections need to be made, you can do so by editing the fields in the form on the right-hand side.
Once your review is complete, click Submit. This will send the form to a Completed status.
User Roles and Entitlements
Admin users must give Project access to Team Members by inviting them to the account and selecting the relevant project(s).
Manager, QA and Scorer user roles are all set at a Project level and can be different on different projects. E.g. User X can be a Manager on Project A and a Scorer on Project B.
Capabilities
Admins
Managers
QA Users
Scoring Users
My Account
By clicking on the icon with your initials on the top right of the screen, you can access the My Account screen. There are several useful links in this screen:
Change password: Provides a link to change your password
Documentation: Provides a link to Iris Documentation
Contact Us: Provides a link to contact us for account-related inquiries and/or troubleshooting support
Logout: Logs you out of the application
Contact Support
If you have any questions about Iris CMS-1500 Reader, please contact our support team here.
