Share via


Zuva DocAI

Embed Contracts AI into your product workflows using Zuva DocAI. No need for AI development from the ground up, leverage the DocAI APIs to extract information from your contracts.

This connector is available in the following products and regions:

Service Class Regions
Logic Apps Standard All Logic Apps regions except the following:
     -   Azure Government regions
     -   Azure China regions
     -   US Department of Defense (DoD)
Power Automate Premium All Power Automate regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Power Apps Premium All Power Apps regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Contact
Name Zuva Support
URL https://zuva.ai/support/
Email support@zuva.ai
Connector Metadata
Publisher Zuva Inc.
Website https://zuva.ai/
Privacy policy https://zuva.ai/privacy/
Categories AI

This Connector enables users to find and extract entities, sentences, and paragraphs from contracts (and related documents), leveraging Zuva's best-in-class Contracts AI. Designed and trained to pinpoint legal clauses across multiple industries and use cases, this connector provides a plug-and-play suite of modules to embed Contracts AI in your workflows. This Connector comes with OCR to read your documents, as well as document classification and normalization capabilities.

Prerequisites

You will need a Zuva account and a DocAI token. Get started by signing up for a free account.

How to get credentials

Zuva DocAI has multiple regional servers. You will need to create an API token for the specific region that you wish to use.

  1. Create and/or sign into your account at zuva.ai.
  2. Navigate to the DocAI console
  3. Select the region you would like to use.
  4. Copy the base URL for the region to your connection.
  5. Create a token and copy it to use in your connection.

See the DocAI quickstart guide for more information about Zuva accounts and tokens.

Get started with your connector

To use the Zuva DocAI connector, you will need to set a flow similar to the following:

Step 1: Obtain a file

For testing purposes, you can create an "Instant cloud flow" in Power Automate. Choose "Manually trigger a flow" and create the flow. Add an input, and choose the "File" type.

Step 2: Submit a file

Add the Submit a file action, and choose the "File Content" from the previous step as the input.

Note: the file should not be transformed in any way (i.e, no base64 encoding). DocAI only accepts raw binary data.

Step 3: Start processing the file

Choose which service you'd like to use by adding one of the following actions:

  • Create Language Classification Request
  • Create Document Classification Request
  • Create Multi-Level Classification Request
  • Create Field Extraction Request
  • Create OCR Request

Each of these accepts the file ID (returned from the Submit a file action) as input.

The field extraction additionally requires field IDs as inputs. Field IDs can be found in the Field Library (sign-in required), from AI trainer if you have trained custom fields, or programmatically using the Get Field List action.

Step 4: Poll for completion of the request

Use a Do Until block (found in the "Control" section), and add the correct status check action to the inside of the block:

  • Get Field Extraction Request Status
  • Get Language Classification Request Status
  • Get Document Classification Request Status
  • Get MLC request Status
  • Get OCR Request Status

The Get ____ status action takes as input the request ID from its corresponding Create ____ Request action.

You should also add a 10 second Delay block inside the Do until block, to ensure that the file has sufficient time to process.

Set the condition for the Do Until block to Is Finished? is equal to true.

Step 4: Get results

Finally, use one of the Get results Action corresponding to your request, using the Request ID from the original Create operation as input:

  • Get Field Extraction Request Text Results
  • Get Language Classification Request Status
  • Get Document Classification Request Status
  • Get MLC request Status
  • Get OCR Results Text
  • Get OCR Results Images

Note that for Language, Document Classification and MLC, the results are included in the Status response.

You may wish to check the DocAI documentation for more information about the structure of field extraction results.

Known issues and limitations

Fields per request

A maximum of 100 fields may be included in a single Create Field Extraction Request action.

Custom fields

The connector does not support any of DocAI's endpoints related to training custom fields or getting an individual field's metadata.

Differences with underlying API

Additionally, please note that connector functionality does not correspond one-to-one with the documentation for the underlying API. In particular, the connector:

  1. Exposes an extra is_finished boolean, which can be used to tell if the request is either complete or failed
  2. All requests operate on single files, rather than batches of multiple files.

Common errors and remedies

Be sure to upload raw binary, rather than base64-encoded strings. You can use the OCR service and check that it returns the expected text.

FAQ

Where can I find additional information about Zuva DocAI?

https://zuva.ai/docai/

Where can I find additional documentation about Zuva DocAI?

https://zuva.ai/documentation/

Creating a connection

The connector supports the following authentication types:

Default Parameters for creating connection. All regions Not shareable

Default

Applicable: All regions

Parameters for creating connection.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name Type Description Required
Token securestring Your DocAI token True
Base URL string e.g. https://us.app.zuva.ai/api/v2 True

Throttling Limits

Name Calls Renewal Period
API calls per connection 100 60 seconds

Actions

Create an OCR Request

Create a new request for OCR to be applied to the specified file.

Create Document Classification Request

Create a request for classification of the specified document.

Create Field Extraction Request

Create a new request for extractions from the specified file.

Create Language Classification Request

Create a request for the language of the specified file.

Create Multi-Level Classification Request

Create a request for multi-level classification of the specified file.

Delete a File

Delete an existing file from Zuva.

Get Document Classification Request Status

Get status and available results for an existing document classification request.

Get Field Extraction Request Results

Get text results from a completed field extraction request.

Get Field Extraction Request Status

Check the status of an existing field extraction request.

Get Field List

Get a list of all fields available to you.

Get Language Classification Request Status

Get status and available results for an existing document classification request.

Get MLC request Status

Get status and available results for an existing MLC request.

Get OCR Request Images

Get the images from a completed OCR request.

Get OCR Request Status

Check the status of an existing OCR request.

Get OCR Request Text

Get the text from a completed OCR request.

Normalize dates

Normalize a string containing one or more dates. For each date found, the endpoint returns a set of integers representing the year, month and day.

Submit a file

Submit a file to Zuva DocAI.

Create an OCR Request

Create a new request for OCR to be applied to the specified file.

Parameters

Name Key Required Type Description
File ID
file_id string

The unique identifier for the file, as returned by the SubmitFile operation.

Returns

Name Path Type Description
OCR Request ID
request_id string

ID used to obtain status and results of the OCR request.

Create Document Classification Request

Create a request for classification of the specified document.

Parameters

Name Key Required Type Description
File ID
file_id string

The unique identifier for the file, as returned by the SubmitFile operation.

Returns

Name Path Type Description
Classification Request ID
request_id string

ID to use to obtain status and results of this request.

Create Field Extraction Request

Create a new request for extractions from the specified file.

Parameters

Name Key Required Type Description
File ID
file_id string

The file to extract text from.

Field IDs
field_ids array of string

The IDs of the fields to extract.

Returns

Name Path Type Description
Extraction Request ID
request_id string

ID to use to obtain status and results of this request.

Create Language Classification Request

Create a request for the language of the specified file.

Parameters

Name Key Required Type Description
File ID
file_id string

The unique identifier for the file, as returned by the SubmitFile operation.

Returns

Name Path Type Description
Language Request ID
request_id string

ID to use to obtain status and results of this request.

Create Multi-Level Classification Request

Create a request for multi-level classification of the specified file.

Parameters

Name Key Required Type Description
File ID
file_id string

The unique identifier for the file, as returned by the SubmitFile operation.

Returns

Name Path Type Description
MLC Request ID
request_id string

ID to use to obtain status and results of this request.

Delete a File

Delete an existing file from Zuva.

Parameters

Name Key Required Type Description
File ID
file_id True string

ID of the file to delete.

Returns

response
string

Get Document Classification Request Status

Get status and available results for an existing document classification request.

Parameters

Name Key Required Type Description
Request ID
request_id True string

Request ID of the document classification request, as returned by CreateDocumentClasssificationRequest.

Returns

Name Path Type Description
Classification Request Status
status string

Status of the request (one of 'queued', 'processing', 'complete' or 'failed').

Is Finished?
is_finished boolean

Boolean indicating whether the request has reached a terminal state (complete or failed).

Classification
classification string

The type of document that was detected.

Is Contract?
is_contract boolean

Whether the document was recognized as a contract or not.

Get Field Extraction Request Results

Get text results from a completed field extraction request.

Parameters

Name Key Required Type Description
Extraction Request Id
request_id True string

Unique identifer of an existing extraction request, as returned by CreateExtractionRequest.

Returns

Name Path Type Description
Results
results array of object

An array of the results of the field extraction.

Field ID
results.field_id string

The unique identifier for the extracted field.

Extractions
results.extractions array of object

An array of results extracted for this particular field.

Text
results.extractions.text string

The text that was extracted for the field.

Spans
results.extractions.spans array of object

Information about the location of the text within the document.

Start
results.extractions.spans.start integer

The index of the first character of the extraction within the document text.

End
results.extractions.spans.end integer

The index of the last character of the extraction within the document text.

Start
results.extractions.spans.pages.start integer

The page number on which the extraction starts.

End
results.extractions.spans.pages.end integer

The page number on which the extraction ends.

Get Field Extraction Request Status

Check the status of an existing field extraction request.

Parameters

Name Key Required Type Description
Extraction Request Id
request_id True string

Unique identifer of an existing extraction request, as returned by CreateExtractionRequest.

Returns

Name Path Type Description
Field Extraction Request Status
status string

Status of the request (one of 'queued', 'processing', 'complete' or 'failed').

Is Finished?
is_finished boolean

Boolean indicating whether the request has reached a terminal state (complete or failed).

Get Field List

Get a list of all fields available to you.

Returns

Name Path Type Description
array of object
Field ID
field_id string

The unique identifier for the field.

Name
name string

The name of the field

Description
description string

A description of the field.

Bias
bias double

The bias used by the underlying ML model.

F-score
f_score double

The F-score of the field, a statistical measure of its accuracy.

Precision
precision double

The precision of the field.

Recall
recall double

The recall of the field.

Document Count
document_count integer

The number of documents the field has been trained on.

Is Custom?
is_custom boolean

Boolean indicating whether the field is custom.

Is trained?
is_trained boolean

Boolean indicating whether a custom field has been trained.

Get Language Classification Request Status

Get status and available results for an existing document classification request.

Parameters

Name Key Required Type Description
Request ID
request_id True string

Request ID of the language classification request, as returned by CreateLanguageRequest.

Returns

Name Path Type Description
Language Request Status
status string

Status of the request (one of 'queued', 'processing', 'complete' or 'failed').

Is Finished?
is_finished boolean

Boolean indicating whether the request has reached a terminal state (complete or failed).

Language
language string

The primary detected language of the document.

Get MLC request Status

Get status and available results for an existing MLC request.

Parameters

Name Key Required Type Description
Request ID
request_id True string

Request ID of the MLC request, as returned by CreateMlcRequest.

Returns

Name Path Type Description
MLC Request Status
status string

Status of the request (one of 'queued', 'processing', 'complete' or 'failed').

Is Finished?
is_finished boolean

Boolean indicating whether the request has reached a terminal state (complete or failed).

Classifications
classifications array of string

The hierarchical classifications of the document.

Get OCR Request Images

Get the images from a completed OCR request.

Parameters

Name Key Required Type Description
OCR Request Id
request_id True string

Unique identifer of an existing OCR request, as returned by CreateOcrRequest.

Returns

A zip file containing each page of the document as an image.

Images
binary

Get OCR Request Status

Check the status of an existing OCR request.

Parameters

Name Key Required Type Description
OCR Request Id
request_id True string

Unique identifer of an existing OCR request, as returned by CreateOcrRequest.

Returns

Name Path Type Description
OCR Request Status
status string

Status of the request (one of 'queued', 'processing', 'complete' or 'failed').

Is Finished?
is_finished boolean

Boolean indicating whether the request has reached a terminal state (complete or failed).

Get OCR Request Text

Get the text from a completed OCR request.

Parameters

Name Key Required Type Description
OCR Request Id
request_id True string

Unique identifer of an existing OCR request, as returned by CreateOcrRequest.

Returns

Name Path Type Description
Text
text string

OCR text of the document.

Normalize dates

Normalize a string containing one or more dates. For each date found, the endpoint returns a set of integers representing the year, month and day.

Parameters

Name Key Required Type Description
Text
text string

The text string to normalize.

Returns

Name Path Type Description
Request ID
request_id string

ID of the request

text
text string

The original text that was provided.

sha-256
sha-256 string

SHA-256 hash of the original text.

date
date array of object

date

Day
date.day integer

The day of the month as an integer.

Month
date.month integer

The month represented as an integer between 1 and 12.

Year
date.year integer

The year represented as an integer.

Submit a file

Submit a file to Zuva DocAI.

Parameters

Name Key Required Type Description
File
File binary

Binary file content or plain text string to upload. Binary content should NOT be Base64-encoded.

Returns

Name Path Type Description
File ID
file_id string

The Zuva-assigned unique identifier for the file.

Content type
attributes.content-type string

Detected MIME content type of the file

Expiration
expiration string

The time at which the file is scheduled to be deleted from DocAI.

Definitions

string

This is the basic data type 'string'.

binary

This is the basic data type 'binary'.