DocAI API Reference

Embed contracts AI into your product workflows using Zuva DocAI.

Get started by making an account, or check out our guides and additional documentation.

Base URLs

Request URLs are composed of the DocAI base URL plus the relative path for a particular resource.

The available public Base URLs are:

Region	Base URL
United States	https://us.app.zuva.ai/api/v2
Europe	https://eu.app.zuva.ai/api/v2

For example, to submit a file to the United States region of DocAI using the POST /files request, the request should be sent to:

https://us.app.zuva.ai/api/v2/files

The Base URL for each region can be found in the DocAI Dashboard (sign-in required).

The cURL examples in this reference use the base URL for the US region. If you plan to use a different region, please change the URL in your requests.

Authentication

All DocAI endpoints use HTTPS and require Bearer authentication.

Each request must include an authorization header with a valid token for the region (base URL) to which the request is made. The authorization header format is:

Authorization: Bearer <token>

To obtain a token, create a free Zuva account or log in, and create your token in the desired region.

Generating client code

This documentation site is built using a machine-readable OpenAPI 3.0 definition, available as a YAML file in the DocAI API repository on Github.

The OpenAPI definition can be used to build API clients in different languages, as well as mock servers for testing.

Files

Upload and manage your files.

Submit a file

Code sample

curl -X POST https://us.app.zuva.ai/api/v2/files \
     -H 'Content-Type: application/octet-stream' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-binary '@/path/to/file.pdf'

POST /files

Upload a file to DocAI.

For best results, uploaded files should be whole documents (rather than pages, paragraphs or fragments).

The content type does not need to be specified, with the exception of eOCR files, which must use the content type application/eocr. If not provided, the content type will be automatically detected and returned in the attributes of the response. Plain text content must be UTF-8 encoded.

For Microsoft Word documents (.doc and .docx extensions), the header value X-Attr-OCR=msword can be used to bypass OCR and instead read the characters and layout directly from the original file.

Files are deleted from the system after 7 days by default, configurable to a maximum of 14 days. Your file's expiration date can be found in the response of this API call

Parameters

Body parameter

<binary file content>

<binary file content>

Name	In	Type	Description
X-Attr-OCR	header	OcrTypeEnum	Optional. The type of OCR operation to perform on the file
X-Attr-MSWord-GenerateImages	header	string	Optional. Indicates whether to generate page images for MS Word documents when performing OCR
body	body	string(binary)	Required. The file content

Enumerated Values

Parameter	Value
X-Attr-OCR	auto
X-Attr-OCR	ocr
X-Attr-OCR	msword
X-Attr-OCR	text
X-Attr-OCR	eocr

Responses

Example responses

201 Response

{
  "attributes": {
    "content-type": "application/pdf",
    "sha-256": "8b9bff906445adb9925abca7c48954155b3bfc9b548163086f001fa6b25760aa"
  },
  "expiration": "2021-10-07T12:07:57Z",
  "file_id": "c5e407f1qk1er7odm6tg",
  "permissions": [
    ""
  ],
  "size": 23849850
}

Status	Schema	Description
201	FileCreatedResponse	The file was uploaded successfully
400	HttpError	A required header was not specified, or contained an invalid value
401	HttpError	Unauthorized
403	HttpError	Forbidden
500	HttpError	Internal Server Error

Delete files

Code sample

curl -X DELETE https://us.app.zuva.ai/api/v2/files?file_id=id_1&file_id=id_2 \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

DELETE /files

Permanently delete all of the specified files. Each file ID should be provided as a query parameter, e.g. /files?file_id=abcde&file_id=fghijk

If any or all file IDs are invalid or not found, the overall response will be 200 Success, and the response body will contain the individual error messages for each file ID.

A maximum of 1000 file IDs can be included in a single query.

Parameters

Name	In	Type	Description
file_id	query	array[string]	Required. File ID

Responses

Example responses

200 Response

[
  {
    "file_id": "5e407f1qk1er7odm6tg",
    "status": "complete"
  }
]

Status	Schema	Description
200	DeleteFileStatusArray	The status of each deletion request.
400	HttpError	Invalid request
401	HttpError	Unauthorized
403	HttpError	Forbidden
500	HttpError	Internal Server Error

Delete file

Code sample

curl -X DELETE https://us.app.zuva.ai/api/v2/files/{file_id} \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

DELETE /files/{file_id}

Delete an existing file. Only the owner of the file may delete it.

Parameters

Name	In	Type	Description
file_id	path	string	Required. File ID

Responses

Status	Schema	Description
204	None	The file was deleted successfully.
400	HttpError	Invalid file ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	File not found.
410	HttpError	File expired
500	HttpError	Internal Server Error

Update file expiry

Code sample

curl -X PUT https://us.app.zuva.ai/api/v2/files/{file_id}/expiration \
     -H 'Accept: application/json' \
     -H 'Expiration: 7d' \
     -H 'Authorization: Bearer {access-token}'

PUT /files/{file_id}/expiration

Update the expiry on a file. The expiration time can be provided as an absolute timestamp in RFC3339 format (e.g. 2022-12-23T12:34:56Z), or as an interval relative to the time the request is made (e.g 12h or 10d).

Parameters

Name	In	Type	Description
file_id	path	string	Required. File ID
Expiration	header	string	Optional. Expiration time for the file

Responses

Example responses

200 Response

{
  "expiration": "2021-10-07T12:07:57Z",
  "file_id": "c5e407f1qk1er7odm6tg"
}

Status	Schema	Description
200	FileUpdatedResponse	The file was updated successfully.
400	HttpError	Invalid file ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	File not found.
500	HttpError	Internal Server Error

Field Extraction

Identify and extract common legal clauses, provisions and data points from unstructured documents and contracts, including ones written in non-standard language.

Create extraction requests

Code sample

curl -X POST https://us.app.zuva.ai/api/v2/extraction \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-raw
'{
  "field_ids": [
    "c83868ae-269a-4a1b-b2af-c53e5f91efca"
  ],
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}'

POST /extraction

Creates a new request for extraction of the specified fields from each of the specified files, returning one request for each file.

A maximum of 100 field IDs and 100 file IDs can be included in each request.

Parameters

Body parameter

{
  "field_ids": [
    "c83868ae-269a-4a1b-b2af-c53e5f91efca"
  ],
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

Name	In	Type	Description
body	body	CreateExtractionRequestsBody	Required. The file IDs to create extraction requests for and field IDs to extract.

Responses

Example responses

See response body for status of each request.

{
  "file_ids": [
    {
      "file_id": "c5e407f1qk1er7odm6tg",
      "field_ids": [
        "c83868ae-269a-4a1b-b2af-c53e5f91efca"
      ],
      "request_id": "c5e463f1qk154j5e3sjg",
      "status": "queued"
    }
  ]
}

400 Response

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  }
}

Status	Schema	Description
202	ExtractionRequestsAccepted	See response body for status of each request.
400	HttpError	Malformed request, missing/invalid `file_ids` or `field_ids` attribute.
401	HttpError	Unauthorized
403	HttpError	Forbidden
500	HttpError	Internal Server Error

Get extraction request

Code sample

curl https://us.app.zuva.ai/api/v2/extraction/{request_id} \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /extraction/{request_id}

Retrieves the status of an extraction request.

Parameters

Name	In	Type	Description
request_id	path	string	Required. Request ID

Responses

Example responses

The status of the extraction request

{
  "file_id": "c5e407f1qk1er7odm6tg",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete"
}

400 Response

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  }
}

Status	Schema	Description
200	ExtractionRequestStatus	The status of the extraction request
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
500	HttpError	Internal Server Error

Get extraction results

Code sample

curl https://us.app.zuva.ai/api/v2/extraction/{request_id}/results/text \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /extraction/{request_id}/results/text

Retrieves the results of an extraction request. The response includes a result object for each field, which may include zero or more extractions of that field from the document.

Parameters

Name	In	Type	Description
request_id	path	string	Required. Request ID

Responses

Example responses

200 Response

{
  "file_id": "cdcpbqd9j3v1l06vsds0",
  "request_id": "cdcpcgt9j3va54jmj4b0",
  "results": [
    {
      "answers": [
        {
          "option": "a",
          "value": "This is a multiple choice answer"
        }
      ],
      "extractions": [
        {
          "currencies": [
            {
              "value": 2347,
              "symbol": "dollars",
              "precision": 2
            }
          ],
          "dates": [
            {
              "day": 28,
              "month": 11,
              "year": 2022
            }
          ],
          "defined_term": {
            "term": "Landlord",
            "spans": [
              {
                "bounds": {
                  "bottom": 2652,
                  "left": 228,
                  "right": 355,
                  "top": 2624
                },
                "bboxes": [
                  {
                    "page": 1,
                    "bounds": [
                      {
                        "bottom": 2652,
                        "left": 228,
                        "right": 355,
                        "top": 2624
                      }
                    ]
                  }
                ],
                "end": 637,
                "pages": {
                  "end": 1,
                  "start": 1
                },
                "score": 0.9999379754341181,
                "start": 632
              }
            ]
          },
          "durations": [
            {
              "unit": "months",
              "value": 4
            }
          ],
          "spans": [
            {
              "bounds": {
                "bottom": 2652,
                "left": 228,
                "right": 355,
                "top": 2624
              },
              "bboxes": [
                {
                  "page": 1,
                  "bounds": [
                    {
                      "bottom": 2652,
                      "left": 228,
                      "right": 355,
                      "top": 2624
                    }
                  ]
                }
              ],
              "end": 637,
              "pages": {
                "end": 1,
                "start": 1
              },
              "score": 0.9999379754341181,
              "start": 632
            }
          ],
          "text": "LEASE"
        }
      ],
      "field_id": "668ee3b5-e15a-439f-9475-05a21755a5c1",
      "field_name": "string"
    }
  ]
}

Status	Schema	Description
200	ExtractionTextResultResponse	The text result of an extraction
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
409	HttpError	Results not ready yet
500	HttpError	Internal Server Error

Get extraction requests

Code sample

curl https://us.app.zuva.ai/api/v2/extractions?request_id=id_1&request_id=id_2 \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /extractions

Retrieves the status of one or more extraction requests. Each request ID should be provided as a query parameter, e.g. /extractions?request_id=abcde&request_id=fghijk

If any or all request ids are invalid or not found, the overall response will be 200 Success, and the response body will contain the individual error messages for each request id.

A maximum of 1000 request IDs can be included in a single query.

Parameters

Name	In	Type	Description
request_id	query	array[string]	Required. Extraction request IDs

Responses

Example responses

200 Response

{
  "errors": {
    "cc1oi51qqhquidfjhiu0": {
      "error": {
        "code": "request_not_found",
        "message": "The specified request ID cannot be found"
      }
    }
  },
  "num_errors": 1,
  "num_found": 1,
  "statuses": {
    "cc1oi51qqhquidfjmiu0": {
      "file_id": "cc1ohrhqqhqthd7h5lag",
      "status": "complete",
      "request_id": "cc1oi51qqhquidfjmiu0"
    }
  }
}

Status	Schema	Description
200	ExtractionStatuses	The status of multiple extraction requests
400	HttpError	Invalid request
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
500	HttpError	Internal Server Error

Multi-Level Classification (MLC)

Find out what type of contracts and contract-related documents you have. The new Multi-Level Classification service provides an order-of-magnitude increase in the number of classification models compared to the classic Document Classification service.

Create MLC requests

Code sample

curl -X POST https://us.app.zuva.ai/api/v2/mlc \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-raw
'{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}'

POST /mlc

Creates an MLC request for each of the specified files.

Parameters

Body parameter

{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

Name	In	Type	Description
body	body	CreateMLCRequest	Required. The fileIDs to create MLC requests for.

Responses

Example responses

See response body for status of each request.

{
  "file_ids": [
    {
      "file_id": "c5e407f1qk1er7odm6tg",
      "request_id": "c5e463f1qk154j5e3sjg",
      "status": "queued"
    }
  ]
}

400 Response

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  }
}

Status	Schema	Description
202	MLCRequestsAccepted	See response body for status of each request.
400	HttpError	Malformed request or missing/invalid `file_ids` attribute.
401	HttpError	Unauthorized
403	HttpError	Forbidden
500	HttpError	Internal Server Error

Get MLC request

Code sample

curl https://us.app.zuva.ai/api/v2/mlc/{request_id} \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /mlc/{request_id}

Retrieves the status of a multi-level classification request and, if the status is complete, its results.

Parameters

Name	In	Type	Description
request_id	path	string	Required. Request ID

Responses

Example responses

The status and results of the document classification request.

{
  "file_id": "c5e407f1qk1er7odm6tg",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete",
  "classifications": [
    "Contract",
    "IP Agt",
    "License Agt"
  ],
  "language": {
    "code": "en",
    "name": "English"
  },
  "is_amendment": false
}

400 Response

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  }
}

Status	Schema	Description
200	MLCStatus	The status and results of the document classification request.
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
500	HttpError	Internal Server Error

Get MLC requests

Code sample

curl https://us.app.zuva.ai/api/v2/mlcs?request_id=id_1&request_id=id_2 \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /mlcs

Retrieves the status of one or more Multi-Level Classification status requests. Each request ID should be provided as a query parameter, e.g. /mlcs?request_id=abcde&request_id=fghijk

If any or all request IDs are invalid or not found, the overall response will be 200 Success, and the response body will contain the individual error messages for each request ID.

A maximum of 1000 request IDs can be included in a single query.

Parameters

Name	In	Type	Description
request_id	query	array[string]	Required. MLC request IDs

Responses

Example responses

200 Response

{
  "errors": {
    "cc1oi51qqhquidfjhiu0": {
      "error": {
        "code": "request_not_found",
        "message": "The specified request ID cannot be found"
      }
    }
  },
  "num_errors": 1,
  "num_found": 1,
  "statuses": {
    "cc1oi51qqhquidfjmiu0": {
      "file_id": "c5e407f1qk1er7odm6tg",
      "status": "complete",
      "request_id": "c5e463f1qk154j5e3sjg",
      "classifications": [
        "Contract",
        "IP Agt",
        "License Agt"
      ]
    }
  }
}

Status	Schema	Description
200	MLCStatuses	The status of multiple MLC requests
400	HttpError	Invalid request
401	HttpError	Unauthorized
403	HttpError	Forbidden
500	HttpError	Internal Server Error

Normalization

(In Alpha) Normalize a string containing currencies, dates or durations.

Normalize Currency

Code sample

curl -X POST https://us.app.zuva.ai/api/v2/normalize/currency \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-raw
'{
  "text": [
    "The rent is two thousand three hundred forty seven dollars"
  ]
}'

POST /normalize/currency

Normalize currencies found within a string, returning an array of currency values and their denominations.

Parameters

Body parameter

{
  "text": [
    "The rent is two thousand three hundred forty seven dollars"
  ]
}

Name	In	Type	Description
body	body	NormalizeCurrencyRequestBody	Required. The string of text to normalize.

Responses

Example responses

200 Response

{
  "request_id": "c5e407f1qk1er7odm6tg",
  "text": "The rent is two thousand three hundred forty seven dollars",
  "sha-256": "9e5073c23ea12c7eb74682089380f9a5b891e3fe2cbe04a3ec89d9d5c004de17",
  "currency": [
    {
      "value": 2347,
      "symbol": "dollars",
      "precision": 2
    }
  ]
}

Status	Schema	Description
200	NormalizeCurrencyResponseBody	See response body for status of request.
400	HttpError	Malformed request, missing/invalid body.

Normalize Date

Code sample

curl -X POST https://us.app.zuva.ai/api/v2/normalize/date \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-raw
'{
  "text": [
    "The lease terminates on Monday, November 28, 2022"
  ]
}'

POST /normalize/date

Normalize dates found within a string, returning an array of date values (day, month, year).

Parameters

Body parameter

{
  "text": [
    "The lease terminates on Monday, November 28, 2022"
  ]
}

Name	In	Type	Description
body	body	NormalizeDateRequestBody	Required. The string of text to normalize.

Responses

Example responses

200 Response

{
  "request_id": "c5e407f1qk1er7odm6tg",
  "text": "The lease terminates on Monday, November 28, 2022",
  "sha-256": "914bbbcb1432e0419aa46042cc09fc908c0b3ce822977ebe62d2530c4dd2386c",
  "date": [
    {
      "day": 28,
      "month": 11,
      "year": 2022
    }
  ]
}

Status	Schema	Description
200	NormalizeDateResponseBody	See response body for status of request.
400	HttpError	Malformed request, missing/invalid body.

Normalize Duration

Code sample

curl -X POST https://us.app.zuva.ai/api/v2/normalize/duration \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-raw
'{
  "text": [
    "The contract expires 4 months after termination"
  ]
}'

POST /normalize/duration

Creates a new duration normalize request for a string, returning a request ID and the normalized duration. Normalize durations found within a string, returning an array of duration values and their units.

Parameters

Body parameter

{
  "text": [
    "The contract expires 4 months after termination"
  ]
}

Name	In	Type	Description
body	body	NormalizeDurationRequestBody	Required. The string of text to normalize.

Responses

Example responses

200 Response

{
  "request_id": "c5e407f1qk1er7odm6tg",
  "text": "The contract expires 4 months after termination",
  "sha-256": "97d7dfd38b649cd6109d0be3f757d65f485d483cce6235294938ca02cd99ed18",
  "duration": [
    {
      "unit": "months",
      "value": 4
    }
  ]
}

Status	Schema	Description
200	NormalizeDurationResponseBody	See response body for status of request.
400	HttpError	Malformed request, missing/invalid body.

OCR

Obtain the text, images and layouts of your documents using Optical Character Recognition.

Create OCR requests

Code sample

curl -X POST https://us.app.zuva.ai/api/v2/ocr \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-raw
'{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}'

POST /ocr

Creates a new OCR request for each of the specified files, returning one request object for each file.

Parameters

Body parameter

{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

Name	In	Type	Description
body	body	CreateOcrRequestsBody	Required. The file IDs to create OCR requests for.

Responses

Example responses

See response body for status of each request.

{
  "file_ids": [
    {
      "file_id": "c5e407f1qk1er7odm6tg",
      "request_id": "c5e463f1qk154j5e3sjg",
      "status": "queued"
    }
  ]
}

400 Response

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  }
}

Status	Schema	Description
202	OcrRequestsAccepted	See response body for status of each request.
400	HttpError	Malformed request, missing/invalid `fileIds` attribute.
401	HttpError	Unauthorized
403	HttpError	Forbidden
500	HttpError	Internal Server Error

Get OCR request

Code sample

curl https://us.app.zuva.ai/api/v2/ocr/{request_id} \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /ocr/{request_id}

Retrieves the status of an OCR request.

Parameters

Name	In	Type	Description
request_id	path	string	Required. Request ID

Responses

Example responses

The status of an OCR request

{
  "file_id": "c5e407f1qk1er7odm6tg",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete",
  "page_count": 10,
  "character_count": 10800,
  "scan_quality": "A",
  "scan_score": 100
}

400 Response

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  }
}

Status	Schema	Description
200	OcrRequestStatus	The status of an OCR request
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
500	HttpError	Internal Server Error

Response Headers

Status	Header	Type	Format	Description
200	X-Attr-OCR	string		The type of OCR operation that was performed.

Get OCR requests

Code sample

curl https://us.app.zuva.ai/api/v2/ocrs?request_id=id_1&request_id=id_2 \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /ocrs

Retrieves the status of one or more OCR status requests. Each request ID should be provided as a query parameter, e.g. /ocrs?request_id=abcde&request_id=fghijk

If any or all request IDs are invalid or not found, the overall response will be 200 Success, and the response body will contain the individual error messages for each request ID.

A maximum of 1000 request IDs can be included in a single query.

Parameters

Name	In	Type	Description
request_id	query	array[string]	Required. OCR request IDs

Responses

Example responses

200 Response

{
  "errors": {
    "cc1oi51qqhquidfjhiu0": {
      "error": {
        "code": "request_not_found",
        "message": "The specified request ID cannot be found"
      }
    }
  },
  "num_errors": 1,
  "num_found": 1,
  "statuses": {
    "cc1oi51qqhquidfjmiu0": {
      "file_id": "c5e407f1qk1er7odm6tg",
      "status": "complete",
      "request_id": "c5e463f1qk154j5e3sjg"
    }
  }
}

Status	Schema	Description
200	OCRStatuses	The status of multiple OCR requests
400	HttpError	Invalid request
401	HttpError	Unauthorized
403	HttpError	Forbidden
500	HttpError	Internal Server Error

Get eOCR document

Code sample

curl https://us.app.zuva.ai/api/v2/ocr/{request_id}/eocr \
     -H 'Accept: application/octet-stream' \
     -H 'Authorization: Bearer {access-token}'

GET /ocr/{request_id}/eocr

Retrieves the document in eOCR format.

Parameters

Name	In	Type	Description
request_id	path	string	Required. Request ID

Responses

Status	Schema	Description
200	string	eOCR document was retrieved successfully.
204	None	No content of this type was found.
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
409	HttpError	OCR results not ready yet
500	HttpError	Internal Server Error

Get OCR images

Code sample

curl https://us.app.zuva.ai/api/v2/ocr/{request_id}/images \
     -H 'Accept: application/octet-stream' \
     -H 'Authorization: Bearer {access-token}'

GET /ocr/{request_id}/images

Retrieves png images of all pages of OCR document as a zip file.

Parameters

Name	In	Type	Description
request_id	path	string	Required. Request ID

Responses

Status	Schema	Description
200	string	Images were retrieved successfully.
204	None	No content of this type was found.
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
409	HttpError	OCR results not ready yet
500	HttpError	Internal Server Error

Get OCR page image

Code sample

curl https://us.app.zuva.ai/api/v2/ocr/{request_id}/images/{page_number} \
     -H 'Accept: image/png' \
     -H 'Authorization: Bearer {access-token}'

GET /ocr/{request_id}/images/{page_number}

Retrieves a png image of one page of an OCR document.

Parameters

Name	In	Type	Description
request_id	path	string	Required. Request ID
page_number	path	integer	Required. Page Number

Responses

Status	Schema	Description
200	string	Image was retrieved successfully.
204	None	No content of this type was found.
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
409	HttpError	OCR results not ready yet
500	HttpError	Internal Server Error

Get OCR layouts

Code sample

curl https://us.app.zuva.ai/api/v2/ocr/{request_id}/layouts \
     -H 'Accept: application/octet-stream' \
     -H 'Authorization: Bearer {access-token}'

GET /ocr/{request_id}/layouts

Gets the layout protobuf binary for an OCR document.

Parameters

Name	In	Type	Description
request_id	path	string	Required. Request ID

Responses

Status	Schema	Description
200	string	Layouts were retrieved successfully.
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
409	HttpError	OCR results not ready yet
500	HttpError	Internal Server Error

Get OCR text

Code sample

curl https://us.app.zuva.ai/api/v2/ocr/{request_id}/text \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /ocr/{request_id}/text

Retrieves the text results of an OCR request. The text is returned as a string without newlines or formatting.

Parameters

Name	In	Type	Description
request_id	path	string	Required. Request ID

Responses

Example responses

200 Response

{
  "request_id": "c5e463f1qk154j5e3sjg",
  "text": "The text of the document"
}

Status	Schema	Description
200	OcrTextResponse	The OCR text result
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
409	HttpError	OCR results not ready yet
500	HttpError	Internal Server Error

Fields

Discover and manage your fields.

Get field list

Code sample

curl https://us.app.zuva.ai/api/v2/fields \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /fields

Lists all fields available to the user.

Metadata for non-custom fields will include all properties, but the scores (precision, recall etc.) will be zero.

Responses

Example responses

200 Response

[
  {
    "bias": 0,
    "description": "Description of the field.",
    "document_count": 0,
    "document_types": [
      {
        "classifications": [
          "string"
        ],
        "percentage": 0
      }
    ],
    "f_score": 0,
    "field_id": "12345678-1234-1234-1234-123456789012",
    "file_ids": [
      "c5e407f1qk1er7odm6tg"
    ],
    "is_custom": true,
    "is_trained": true,
    "jurisdictions": [
      {
        "country": {
          "code": "string",
          "name": "string"
        },
        "regions": [
          "string"
        ]
      }
    ],
    "languages": [
      {
        "language": "string",
        "percentage": 0
      }
    ],
    "name": "Field Name",
    "normalization_type": "string",
    "precision": 0,
    "recall": 0,
    "tags": [
      "string"
    ]
  }
]

Status	Schema	Description
200	FieldListResponse	List of fields with metadata.
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
500	HttpError	Internal Server Error

Create a new field

Code sample

curl -X POST https://us.app.zuva.ai/api/v2/fields \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-raw
'{
  "description": "A description of the field",
  "name": "My New Field",
  "from_field_id": "12345678-1234-1234-1234-123456789012"
}'

POST /fields

Creates a new field and returns its field ID.

The optional from_field_id parameter can be provided in order to copy an existing field as a starting point for further training.

Parameters

Body parameter

{
  "description": "A description of the field",
  "name": "My New Field",
  "from_field_id": "12345678-1234-1234-1234-123456789012"
}

Name	In	Type	Description
body	body	PostFieldRequest	Required. The metadata for the new field

Responses

Example responses

201 Response

{
  "field_id": "12345678-1234-1234-1234-123456789012"
}

Status	Schema	Description
201	NewFieldResponse	ID of newly created field
400	HttpError	Specified `from_field_id` does not exist
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
500	HttpError	Internal Server Error

Get field accuracy

Code sample

curl https://us.app.zuva.ai/api/v2/fields/{field_id}/accuracy \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /fields/{field_id}/accuracy

Gets the scores for a custom field, including precision, recall and f-score.

Parameters

Name	In	Type	Description
field_id	path	string	Required. Field ID

Responses

Example responses

200 Response

{
  "example_count": 0,
  "f_score": 0,
  "precision": 0,
  "recall": 0
}

Status	Schema	Description
200	FieldAccuracyResponse	The field's accuracy
400	HttpError	Invalid field ID
404	HttpError	Field not found.
409	HttpError	The field has not finished training yet
500	HttpError	Internal Server Error

Get field metadata

Code sample

curl https://us.app.zuva.ai/api/v2/fields/{field_id}/metadata \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /fields/{field_id}/metadata

Gets field metadata and returns field_id, name, description, read_only, is_trained, file_ids

Parameters

Name	In	Type	Description
field_id	path	string	Required. Field ID

Responses

Example responses

200 Response

{
  "description": "string",
  "document_types": [
    {
      "classifications": [
        "string"
      ],
      "percentage": 0
    }
  ],
  "field_id": "12345678-1234-1234-1234-123456789012",
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ],
  "is_trained": true,
  "jurisdictions": [
    {
      "country": {
        "code": "string",
        "name": "string"
      },
      "regions": [
        "string"
      ]
    }
  ],
  "languages": [
    {
      "language": "string",
      "percentage": 0
    }
  ],
  "name": "string",
  "normalization_type": "string",
  "read_only": true,
  "tags": [
    "string"
  ]
}

Status	Schema	Description
200	FieldMetadataResponse	The field's metadata
400	HttpError	Invalid field ID
404	HttpError	Field not found.
500	HttpError	Internal Server Error

Update field metadata

Code sample

curl -X PUT https://us.app.zuva.ai/api/v2/fields/{field_id}/metadata \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-raw
'{
  "description": "New description",
  "name": "New Name"
}'

PUT /fields/{field_id}/metadata

Update the name and description of a custom field.

Parameters

Body parameter

{
  "description": "New description",
  "name": "New Name"
}

Name	In	Type	Description
field_id	path	string	Required. Field ID
body	body	PutFieldMetadataRequest	Required. The updated metadata for the field

Responses

Status	Schema	Description
204	None	The metadata for the field was successfully updated
400	HttpError	Invalid field ID
404	HttpError	Field not found.
405	HttpError	Cannot update a read-only field
500	HttpError	Internal Server Error

Get field validation details

Code sample

curl https://us.app.zuva.ai/api/v2/fields/{field_id}/validation-details \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /fields/{field_id}/validation-details

Returns the details (file ID, type, location) of each extraction used for validation during training of the field.

Possible values of type are:

tp: True Positive - an annotation added by the user that the AI agrees with.
fn: False Negative - an annotation added by the user that the AI disagrees with.
fp: False Positive - an annotation that the user did not add, but that the AI suggests they add to training.
na: Not Applicable - an annotation that was not used for validation, either because it was part of the initial training batch, or because the file was a duplicate of a file that was already trained on.

If the example type is tp or fp, the location refers to the text found by the ML. If the example type is fn or na, the location refers to the original user highlight that was missed.

Parameters

Name	In	Type	Description
field_id	path	string	Required. Field ID

Responses

Example responses

200 Response

[
  {
    "file_id": "c5e407f1qk1er7odm6tg",
    "location": [
      26952,
      27310
    ],
    "type": "tp"
  }
]

Status	Schema	Description
200	FieldValidationDetailsResponse	The field's validation details
400	HttpError	Invalid field ID
404	HttpError	Field not found.
409	HttpError	A training request is in progress for this field
500	HttpError	Internal Server Error

Training

Train fields on your extractions.

Create training request

Code sample

curl -X POST https://us.app.zuva.ai/api/v2/fields/{field_id}/train \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}' \
     --data-raw
'[
  {
    "file_id": "c5e407f1qk1er7odm6tg",
    "locations": [
      {
        "start": 123,
        "end": 456
      }
    ]
  }
]'

POST /fields/{field_id}/train

Starts training on a field and returns the request id.

The start and end locations refer to the positions of the first and last characters of an example text span that the model should learn to extract. The character positions must be given in terms of Zuva's OCR representation of the document, which can be obtained from the GET OCR layouts endpoint.

Parameters

Body parameter

[
  {
    "file_id": "c5e407f1qk1er7odm6tg",
    "locations": [
      {
        "start": 123,
        "end": 456
      }
    ]
  }
]

Name	In	Type	Description
field_id	path	string	Required. Field ID
body	body	FieldTrainingRequest	Required. The data to train the new field on.

Responses

Example responses

The status of the training request

{
  "field_id": "12345678-1234-1234-1234-123456789012",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "queued"
}

400 Response

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  }
}

Status	Schema	Description
202	TrainingRequestStatus	The status of the training request
400	HttpError	Invalid request body
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Field not found.
409	HttpError	Conflict: training request ongoing
500	HttpError	Internal Server Error

Get training request

Code sample

curl https://us.app.zuva.ai/api/v2/fields/{field_id}/train/{request_id} \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {access-token}'

GET /fields/{field_id}/train/{request_id}

Retrieves the status of a field training request.

Parameters

Name	In	Type	Description
field_id	path	string	Required. Field ID
request_id	path	string	Required. Request ID

Responses

Example responses

The status of the training request

{
  "field_id": "12345678-1234-1234-1234-123456789012",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete"
}

400 Response

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  }
}

Status	Schema	Description
200	TrainingRequestStatus	The status of the training request
400	HttpError	Invalid request ID
401	HttpError	Unauthorized
403	HttpError	Forbidden
404	HttpError	Request not found.
500	HttpError	Internal Server Error

Schemas

Answer

Properties

{
  "option": "a",
  "value": "This is a multiple choice answer"
}

Name	Type	Required	Description
option	string	true
value	string	true

BoundingBox

Properties

{
  "bottom": 2652,
  "left": 228,
  "right": 355,
  "top": 2624
}

Name	Type	Required
bottom	integer	true
left	integer	true
right	integer	true
top	integer	true

BoundingBoxSummary

This bounding box captures the top left position of the first character and the bottom right position of the last character of the extraction.

Properties

{
  "bottom": 2652,
  "left": 228,
  "right": 355,
  "top": 2624
}

Name	Type	Required
bottom	integer	true
left	integer	true
right	integer	true
top	integer	true

BoundingBoxesByPage

Bounding boxes for each line of the extraction that occur on a particular page.

Properties

{
  "page": 1,
  "bounds": [
    {
      "bottom": 2652,
      "left": 228,
      "right": 355,
      "top": 2624
    }
  ]
}

Name	Type	Required	Description
page	integer	true
bounds	[BoundingBox]	true

CharacterSpan

Properties

{
  "bounds": {
    "bottom": 2652,
    "left": 228,
    "right": 355,
    "top": 2624
  },
  "bboxes": [
    {
      "page": 1,
      "bounds": [
        {
          "bottom": 2652,
          "left": 228,
          "right": 355,
          "top": 2624
        }
      ]
    }
  ],
  "end": 637,
  "pages": {
    "end": 1,
    "start": 1
  },
  "score": 0.9999379754341181,
  "start": 632
}

Name	Type	Required	Description
bounds	BoundingBoxSummary	false	This bounding box captures the top left position of the first character and the bottom right position of the last character of the extraction.
bboxes	[BoundingBoxesByPage]	true	[Bounding boxes for each line of the extraction that occur on a particular page.]
end	integer	true
pages	Span	true
score	number(double)	true
start	integer	true

ClassificationPercentage

Properties

{
  "classifications": [
    "string"
  ],
  "percentage": 0
}

Name	Type	Required	Description
classifications	[string]	true
percentage	number	true

Country

Properties

{
  "code": "string",
  "name": "string"
}

Name	Type	Required	Description
code	string	true	The ISO 3166-1 alpha-2 code, eg. "CA".
name	string	true	The ISO 3166 country name, eg. "Canada".

CreateExtractionRequestsBody

Properties

{
  "field_ids": [
    "c83868ae-269a-4a1b-b2af-c53e5f91efca"
  ],
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

Name	Type	Required	Description
field_ids	[string]	true
file_ids	[string]	true

CreateMLCRequest

Properties

{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

Name	Type	Required	Description
file_ids	[string]	true	The files to classify

CreateOcrRequestsBody

Properties

{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

Name	Type	Required	Description
file_ids	[string]	true

CurrencyValues

Properties

{
  "value": 2347,
  "symbol": "dollars",
  "precision": 2
}

Name	Type	Required
value	string	true
symbol	string	true
precision	integer	true

DateValues

Properties

{
  "day": 28,
  "month": 11,
  "year": 2022
}

Name	Type	Required
day	integer	true
month	integer	true
year	integer	true

DefinedTerm

Properties

{
  "term": "Landlord",
  "spans": [
    {
      "bounds": {
        "bottom": 2652,
        "left": 228,
        "right": 355,
        "top": 2624
      },
      "bboxes": [
        {
          "page": 1,
          "bounds": [
            {
              "bottom": 2652,
              "left": 228,
              "right": 355,
              "top": 2624
            }
          ]
        }
      ],
      "end": 637,
      "pages": {
        "end": 1,
        "start": 1
      },
      "score": 0.9999379754341181,
      "start": 632
    }
  ]
}

Name	Type	Required	Description
term	string	true
spans	[CharacterSpan]	true

DeleteFileStatus

Properties

{
  "file_id": "5e407f1qk1er7odm6tg",
  "status": "complete"
}

Name	Type	Required	Description
file_id	string	true
status	string	true

DeleteFileStatusArray

Properties

[
  {
    "file_id": "5e407f1qk1er7odm6tg",
    "status": "complete"
  }
]

Name	Type	Required	Description
anonymous	[DeleteFileStatus]	false

DurationValues

Properties

{
  "unit": "months",
  "value": 4
}

Name	Type	Required	Description
unit	string	true
value	integer	true

ExtractionCreatedResponse

Properties

{
  "file_id": "c5e407f1qk1er7odm6tg",
  "field_ids": [
    "c83868ae-269a-4a1b-b2af-c53e5f91efca"
  ],
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete"
}

Name	Type	Required
file_id	string	true
field_ids	[string]	true
request_id	string	true
status	StatusEnum	true

ExtractionRequestStatus

Properties

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  },
  "file_id": "c5e407f1qk1er7odm6tg",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete"
}

Name	Type	Required
error	HttpErrorDetails	false
file_id	string	true
request_id	string	true
status	StatusEnum	true

ExtractionRequestsAccepted

Properties

{
  "file_ids": [
    {
      "file_id": "c5e407f1qk1er7odm6tg",
      "field_ids": [
        "c83868ae-269a-4a1b-b2af-c53e5f91efca"
      ],
      "request_id": "c5e463f1qk154j5e3sjg",
      "status": "complete"
    }
  ]
}

Name	Type	Required	Description
file_ids	[ExtractionCreatedResponse]	true

ExtractionResult

A Result contains an array of all extractions of a field from the file.

Properties

{
  "answers": [
    {
      "option": "a",
      "value": "This is a multiple choice answer"
    }
  ],
  "extractions": [
    {
      "currencies": [
        {
          "value": 2347,
          "symbol": "dollars",
          "precision": 2
        }
      ],
      "dates": [
        {
          "day": 28,
          "month": 11,
          "year": 2022
        }
      ],
      "defined_term": {
        "term": "Landlord",
        "spans": [
          {
            "bounds": {
              "bottom": 2652,
              "left": 228,
              "right": 355,
              "top": 2624
            },
            "bboxes": [
              {
                "page": 1,
                "bounds": [
                  {
                    "bottom": 2652,
                    "left": 228,
                    "right": 355,
                    "top": 2624
                  }
                ]
              }
            ],
            "end": 637,
            "pages": {
              "end": 1,
              "start": 1
            },
            "score": 0.9999379754341181,
            "start": 632
          }
        ]
      },
      "durations": [
        {
          "unit": "months",
          "value": 4
        }
      ],
      "spans": [
        {
          "bounds": {
            "bottom": 2652,
            "left": 228,
            "right": 355,
            "top": 2624
          },
          "bboxes": [
            {
              "page": 1,
              "bounds": [
                {
                  "bottom": 2652,
                  "left": 228,
                  "right": 355,
                  "top": 2624
                }
              ]
            }
          ],
          "end": 637,
          "pages": {
            "end": 1,
            "start": 1
          },
          "score": 0.9999379754341181,
          "start": 632
        }
      ],
      "text": "LEASE"
    }
  ],
  "field_id": "668ee3b5-e15a-439f-9475-05a21755a5c1",
  "field_name": "string"
}

Name	Type	Required	Description
answers	[Answer]	false
extractions	[TextExtraction]	true	[A `Result` contains an array of all extractions of a field from the file.]
field_id	string	true
field_name	string	true

ExtractionStatuses

Properties

{
  "errors": {
    "cc1oi51qqhquidfjhiu0": {
      "error": {
        "code": "request_not_found",
        "message": "The specified request ID cannot be found"
      }
    }
  },
  "num_errors": 1,
  "num_found": 1,
  "statuses": {
    "cc1oi51qqhquidfjmiu0": {
      "file_id": "cc1ohrhqqhqthd7h5lag",
      "status": "complete",
      "request_id": "cc1oi51qqhquidfjmiu0"
    }
  }
}

Name	Type	Required
errors	object	true
» additionalProperties	HttpError	false
num_errors	integer	true
num_found	integer	true
statuses	object	true
» additionalProperties	ExtractionRequestStatus	false

ExtractionTextResultResponse

Properties

{
  "file_id": "cdcpbqd9j3v1l06vsds0",
  "request_id": "cdcpcgt9j3va54jmj4b0",
  "results": [
    {
      "answers": [
        {
          "option": "a",
          "value": "This is a multiple choice answer"
        }
      ],
      "extractions": [
        {
          "currencies": [
            {
              "value": 2347,
              "symbol": "dollars",
              "precision": 2
            }
          ],
          "dates": [
            {
              "day": 28,
              "month": 11,
              "year": 2022
            }
          ],
          "defined_term": {
            "term": "Landlord",
            "spans": [
              {
                "bounds": {
                  "bottom": 2652,
                  "left": 228,
                  "right": 355,
                  "top": 2624
                },
                "bboxes": [
                  {
                    "page": 1,
                    "bounds": [
                      {
                        "bottom": 2652,
                        "left": 228,
                        "right": 355,
                        "top": 2624
                      }
                    ]
                  }
                ],
                "end": 637,
                "pages": {
                  "end": 1,
                  "start": 1
                },
                "score": 0.9999379754341181,
                "start": 632
              }
            ]
          },
          "durations": [
            {
              "unit": "months",
              "value": 4
            }
          ],
          "spans": [
            {
              "bounds": {
                "bottom": 2652,
                "left": 228,
                "right": 355,
                "top": 2624
              },
              "bboxes": [
                {
                  "page": 1,
                  "bounds": [
                    {
                      "bottom": 2652,
                      "left": 228,
                      "right": 355,
                      "top": 2624
                    }
                  ]
                }
              ],
              "end": 637,
              "pages": {
                "end": 1,
                "start": 1
              },
              "score": 0.9999379754341181,
              "start": 632
            }
          ],
          "text": "LEASE"
        }
      ],
      "field_id": "668ee3b5-e15a-439f-9475-05a21755a5c1",
      "field_name": "string"
    }
  ]
}

Name	Type	Required	Description
file_id	string	true
request_id	string	true
results	[ExtractionResult]	true	[A `Result` contains an array of all extractions of a field from the file.]

FieldAccuracyResponse

Properties

{
  "example_count": 0,
  "f_score": 0,
  "precision": 0,
  "recall": 0
}

Name	Type	Required
example_count	integer	true
f_score	number	true
precision	number	true
recall	number	true

FieldListResponse

Properties

[
  {
    "bias": 0,
    "description": "Description of the field.",
    "document_count": 0,
    "document_types": [
      {
        "classifications": [
          "string"
        ],
        "percentage": 0
      }
    ],
    "f_score": 0,
    "field_id": "12345678-1234-1234-1234-123456789012",
    "file_ids": [
      "c5e407f1qk1er7odm6tg"
    ],
    "is_custom": true,
    "is_trained": true,
    "jurisdictions": [
      {
        "country": {
          "code": "string",
          "name": "string"
        },
        "regions": [
          "string"
        ]
      }
    ],
    "languages": [
      {
        "language": "string",
        "percentage": 0
      }
    ],
    "name": "Field Name",
    "normalization_type": "string",
    "precision": 0,
    "recall": 0,
    "tags": [
      "string"
    ]
  }
]

Name	Type	Required	Description
anonymous	[FieldListResponseElement]	false

FieldListResponseElement

Properties

{
  "bias": 0,
  "description": "Description of the field.",
  "document_count": 0,
  "document_types": [
    {
      "classifications": [
        "string"
      ],
      "percentage": 0
    }
  ],
  "f_score": 0,
  "field_id": "12345678-1234-1234-1234-123456789012",
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ],
  "is_custom": true,
  "is_trained": true,
  "jurisdictions": [
    {
      "country": {
        "code": "string",
        "name": "string"
      },
      "regions": [
        "string"
      ]
    }
  ],
  "languages": [
    {
      "language": "string",
      "percentage": 0
    }
  ],
  "name": "Field Name",
  "normalization_type": "string",
  "precision": 0,
  "recall": 0,
  "tags": [
    "string"
  ]
}

Name	Type	Required
bias	number	true
description	string	true
document_count	integer	true
document_types	[ClassificationPercentage]	true
f_score	number	true
field_id	string	true
file_ids	[string]	true
is_custom	boolean	true
is_trained	boolean	true
jurisdictions	[Jurisdiction]	true
languages	[LanguagePercentage]	true
name	string	true
normalization_type	string	true
precision	number	true
recall	number	true
tags	[string]	true

FieldMetadataResponse

Properties

{
  "description": "string",
  "document_types": [
    {
      "classifications": [
        "string"
      ],
      "percentage": 0
    }
  ],
  "field_id": "12345678-1234-1234-1234-123456789012",
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ],
  "is_trained": true,
  "jurisdictions": [
    {
      "country": {
        "code": "string",
        "name": "string"
      },
      "regions": [
        "string"
      ]
    }
  ],
  "languages": [
    {
      "language": "string",
      "percentage": 0
    }
  ],
  "name": "string",
  "normalization_type": "string",
  "read_only": true,
  "tags": [
    "string"
  ]
}

Name	Type	Required
description	string	true
document_types	[ClassificationPercentage]	true
field_id	string	true
file_ids	[string]	true
is_trained	boolean	true
jurisdictions	[Jurisdiction]	true
languages	[LanguagePercentage]	true
name	string	true
normalization_type	string	true
read_only	boolean	true
tags	[string]	true

FieldTrainingRequest

Properties

{
  "file_id": [
    0
  ],
  "locations": [
    {
      "end": 456,
      "start": 123
    }
  ]
}

Name	Type	Required	Description
file_id	[integer]	true
locations	[Location]	true

FieldValidationDetails

Properties

{
  "file_id": "c5e407f1qk1er7odm6tg",
  "location": [
    26952,
    27310
  ],
  "type": "tp"
}

Name	Type	Required	Description
file_id	string	true
location	[integer]	true	The start and end character locations of the extraction.
type	FieldValidationType	true

FieldValidationDetailsResponse

Properties

[
  {
    "file_id": "c5e407f1qk1er7odm6tg",
    "location": [
      26952,
      27310
    ],
    "type": "tp"
  }
]

Name	Type	Required	Description
anonymous	[FieldValidationDetails]	false

FieldValidationType

string

Enumerated Values

Value
tp
fn
fp
na

FileAttributes

Properties

{
  "content-type": "application/pdf",
  "sha-256": "8b9bff906445adb9925abca7c48954155b3bfc9b548163086f001fa6b25760aa"
}

Name	Type	Required	Description
content-type	string	true	The provided or detected MIME type of the File.
sha-256	string	true	The SHA-256 hash of the file's contents

FileCreatedResponse

Properties

{
  "attributes": {
    "content-type": "application/pdf",
    "sha-256": "8b9bff906445adb9925abca7c48954155b3bfc9b548163086f001fa6b25760aa"
  },
  "expiration": "2021-10-07T12:07:57Z",
  "file_id": "c5e407f1qk1er7odm6tg",
  "permissions": [
    ""
  ],
  "size": 23849850
}

Name	Type	Required	Description
attributes	FileAttributes	true
expiration	string	true	The file expiration in RFC3339 format
file_id	string	true	The ID of the created file resource
permissions	[string]	true	Unused
size	integer	true	The file size in bytes

FileUpdatedResponse

Properties

{
  "expiration": "2021-10-07T12:07:57Z",
  "file_id": "c5e407f1qk1er7odm6tg"
}

Name	Type	Required	Description
expiration	string	false	The file expiration in RFC3339 format
file_id	string	false	The ID of the updated file resource

HttpError

Properties

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  }
}

Name	Type	Required	Description
error	HttpErrorDetails	true

HttpErrorDetails

Properties

{
  "code": "http-error",
  "message": "Something went wrong, please try again later."
}

Name	Type	Required	Description
code	string	true	A unique string identifying the error.
message	string	true	An error message providing more details and potential steps to resolve.

Jurisdiction

Properties

{
  "country": {
    "code": "string",
    "name": "string"
  },
  "regions": [
    "string"
  ]
}

Name	Type	Required	Description
country	Country	true
regions	[string]	true	Any additional state/provincial specifications, eg. ["British Columbia", "Ontario"].

LanguagePercentage

Properties

{
  "language": "string",
  "percentage": 0
}

Name	Type	Required	Description
language	string	true
percentage	number	true

Location

Properties

{
  "end": 456,
  "start": 123
}

Name	Type	Required	Description
end	integer	true
start	integer	true

MLCLanguage

Properties

{
  "code": "en",
  "name": "English"
}

Name	Type	Required	Description
code	string	true
name	string	true

MLCRequestsAccepted

Properties

{
  "file_ids": [
    {
      "classifications": [
        "string"
      ],
      "is_amendment": true,
      "is_master_agreement": false,
      "language": {
        "code": "en",
        "name": "English"
      },
      "error": {
        "code": "http-error",
        "message": "Something went wrong, please try again later."
      },
      "file_id": "c5e407f1qk1er7odm6tg",
      "request_id": "c5e463f1qk154j5e3sjg",
      "status": "complete"
    }
  ]
}

Name	Type	Required	Description
file_ids	[MLCStatus]	true

MLCStatus

Properties

{
  "classifications": [
    "string"
  ],
  "is_amendment": true,
  "is_master_agreement": false,
  "language": {
    "code": "en",
    "name": "English"
  },
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  },
  "file_id": "c5e407f1qk1er7odm6tg",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete"
}

Name	Type	Required
classifications	[string]	false
is_amendment	boolean	false
is_master_agreement	boolean	false
language	MLCLanguage	false
error	HttpErrorDetails	false
file_id	string	true
request_id	string	true
status	StatusEnum	true

MLCStatuses

Properties

{
  "errors": {
    "cc1oi51qqhquidfjhiu0": {
      "error": {
        "code": "request_not_found",
        "message": "The specified request ID cannot be found"
      }
    }
  },
  "num_errors": 1,
  "num_found": 1,
  "statuses": {
    "cc1oi51qqhquidfjmiu0": {
      "file_id": "c5e407f1qk1er7odm6tg",
      "status": "complete",
      "request_id": "c5e463f1qk154j5e3sjg",
      "classifications": [
        "Contract",
        "IP Agt",
        "License Agt"
      ]
    }
  }
}

Name	Type	Required
errors	object	true
» additionalProperties	HttpError	false
num_errors	integer	true
num_found	integer	true
statuses	object	true
» additionalProperties	MLCStatus	false

NewFieldResponse

Properties

{
  "field_id": "12345678-1234-1234-1234-123456789012"
}

Name	Type	Required	Description
field_id	string	false

NormalizeCurrencyRequestBody

Properties

{
  "text": [
    "The rent is two thousand three hundred forty seven dollars"
  ]
}

Name	Type	Required	Description
text	string	true

NormalizeCurrencyResponseBody

Properties

{
  "request_id": "c5e407f1qk1er7odm6tg",
  "text": "The rent is two thousand three hundred forty seven dollars",
  "sha-256": "9e5073c23ea12c7eb74682089380f9a5b891e3fe2cbe04a3ec89d9d5c004de17",
  "currency": [
    {
      "value": 2347,
      "symbol": "dollars",
      "precision": 2
    }
  ]
}

Name	Type	Required
request_id	string	true
text	string	true
sha-256	string	true
currency	[CurrencyValues]	true

NormalizeDateRequestBody

Properties

{
  "text": [
    "The lease terminates on Monday, November 28, 2022"
  ]
}

Name	Type	Required	Description
text	string	true

NormalizeDateResponseBody

Properties

{
  "request_id": "c5e407f1qk1er7odm6tg",
  "text": "The lease terminates on Monday, November 28, 2022",
  "sha-256": "914bbbcb1432e0419aa46042cc09fc908c0b3ce822977ebe62d2530c4dd2386c",
  "date": [
    {
      "day": 28,
      "month": 11,
      "year": 2022
    }
  ]
}

Name	Type	Required
request_id	string	true
text	string	true
sha-256	string	true
date	[DateValues]	true

NormalizeDurationRequestBody

Properties

{
  "text": [
    "The contract expires 4 months after termination"
  ]
}

Name	Type	Required	Description
text	string	true

NormalizeDurationResponseBody

Properties

{
  "request_id": "c5e407f1qk1er7odm6tg",
  "text": "The contract expires 4 months after termination",
  "sha-256": "97d7dfd38b649cd6109d0be3f757d65f485d483cce6235294938ca02cd99ed18",
  "duration": [
    {
      "unit": "months",
      "value": 4
    }
  ]
}

Name	Type	Required
request_id	string	true
text	string	true
sha-256	string	true
duration	[DurationValues]	true

OCRStatuses

Properties

{
  "errors": {
    "cc1oi51qqhquidfjhiu0": {
      "error": {
        "code": "request_not_found",
        "message": "The specified request ID cannot be found"
      }
    }
  },
  "num_errors": 1,
  "num_found": 1,
  "statuses": {
    "cc1oi51qqhquidfjmiu0": {
      "file_id": "c5e407f1qk1er7odm6tg",
      "status": "complete",
      "request_id": "c5e463f1qk154j5e3sjg"
    }
  }
}

Name	Type	Required
errors	object	true
» additionalProperties	HttpError	false
num_errors	integer	true
num_found	integer	true
statuses	object	true
» additionalProperties	OcrRequestStatus	false

OcrRequestStatus

Properties

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  },
  "file_id": "c5e407f1qk1er7odm6tg",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete",
  "page_count": 10,
  "character_count": 10000,
  "scan_quality": "A",
  "scan_score": 100
}

Name	Type	Required
error	HttpErrorDetails	false
file_id	string	true
request_id	string	true
status	StatusEnum	true
page_count	integer	false
character_count	integer	false
scan_quality	string	false
scan_score	integer	false

OcrRequestsAccepted

Properties

{
  "file_ids": [
    {
      "error": {
        "code": "http-error",
        "message": "Something went wrong, please try again later."
      },
      "file_id": "c5e407f1qk1er7odm6tg",
      "request_id": "c5e463f1qk154j5e3sjg",
      "status": "complete",
      "page_count": 10,
      "character_count": 10000,
      "scan_quality": "A",
      "scan_score": 100
    }
  ]
}

Name	Type	Required	Description
file_ids	[OcrRequestStatus]	true

OcrTextResponse

Properties

{
  "request_id": "c5e463f1qk154j5e3sjg",
  "text": "The text of the document"
}

Name	Type	Required	Description
request_id	string	true
text	string	true

OcrTypeEnum

string

Enumerated Values

Value
auto
ocr
msword
text
eocr

PostFieldRequest

Properties

{
  "description": "A description of the field",
  "name": "My New Field",
  "from_field_id": "12345678-1234-1234-1234-123456789012"
}

Name	Type	Required	Description
description	string	false
name	string	true
from_field_id	string	false	ID of an existing field to copy

PutFieldMetadataRequest

Properties

{
  "description": "New description",
  "name": "New Name"
}

Name	Type	Required	Description
description	string	false
name	string	false

Span

Properties

{
  "end": 1,
  "start": 1
}

Name	Type	Required	Description
end	integer	true
start	integer	true

SpanIssue

Properties

{
  "file_id": "cdcpbqd9j3v1l06vsds0",
  "span_problems": [
    {
      "index": 0,
      "spans": [
        {
          "end": 0,
          "start": 0,
          "label": 0
        }
      ],
      "issue_type": "Invalid Span"
    }
  ]
}

Name	Type	Required	Description
file_id	string	false
span_problems	[SpanProblems]	false

SpanIssues

Properties

[
  {
    "file_id": "cdcpbqd9j3v1l06vsds0",
    "span_problems": [
      {
        "index": 0,
        "spans": [
          {
            "end": 0,
            "start": 0,
            "label": 0
          }
        ],
        "issue_type": "Invalid Span"
      }
    ]
  }
]

Name	Type	Required	Description
anonymous	[SpanIssue]	false

SpanProblems

Properties

{
  "index": 0,
  "spans": [
    {
      "end": 0,
      "start": 0,
      "label": 0
    }
  ],
  "issue_type": "Invalid Span"
}

Name	Type	Required
index	integer	false
spans	[Spans]	false
issue_type	string	false

Spans

Properties

{
  "end": 0,
  "start": 0,
  "label": 0
}

Name	Type	Required
end	integer	false
start	integer	false
label	integer	false

StatusEnum

string

Enumerated Values

Value
queued
processing
complete
failed

TextExtraction

A Result contains an array of all extractions of a field from the file.

Properties

{
  "currencies": [
    {
      "value": 2347,
      "symbol": "dollars",
      "precision": 2
    }
  ],
  "dates": [
    {
      "day": 28,
      "month": 11,
      "year": 2022
    }
  ],
  "defined_term": {
    "term": "Landlord",
    "spans": [
      {
        "bounds": {
          "bottom": 2652,
          "left": 228,
          "right": 355,
          "top": 2624
        },
        "bboxes": [
          {
            "page": 1,
            "bounds": [
              {
                "bottom": 2652,
                "left": 228,
                "right": 355,
                "top": 2624
              }
            ]
          }
        ],
        "end": 637,
        "pages": {
          "end": 1,
          "start": 1
        },
        "score": 0.9999379754341181,
        "start": 632
      }
    ]
  },
  "durations": [
    {
      "unit": "months",
      "value": 4
    }
  ],
  "spans": [
    {
      "bounds": {
        "bottom": 2652,
        "left": 228,
        "right": 355,
        "top": 2624
      },
      "bboxes": [
        {
          "page": 1,
          "bounds": [
            {
              "bottom": 2652,
              "left": 228,
              "right": 355,
              "top": 2624
            }
          ]
        }
      ],
      "end": 637,
      "pages": {
        "end": 1,
        "start": 1
      },
      "score": 0.9999379754341181,
      "start": 632
    }
  ],
  "text": "LEASE"
}

Name	Type	Required
currencies	[CurrencyValues]	false
dates	[DateValues]	false
defined_term	DefinedTerm	false
durations	[DurationValues]	false
spans	[CharacterSpan]	false
text	string	false

TrainingRequestStatus

Properties

{
  "error": {
    "error": {
      "code": "http-error",
      "message": "Something went wrong, please try again later."
    }
  },
  "field_id": "12345678-1234-1234-1234-123456789012",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete",
  "span_issues": [
    {
      "file_id": "cdcpbqd9j3v1l06vsds0",
      "span_problems": [
        {
          "index": 0,
          "spans": [
            {
              "end": 0,
              "start": 0,
              "label": 0
            }
          ],
          "issue_type": "Invalid Span"
        }
      ]
    }
  ]
}

Name	Type	Required
error	HttpError	false
field_id	string	true
request_id	string	true
status	StatusEnum	true
span_issues	SpanIssues	false