Zuva API Reference

Embed contracts AI into your product workflows using the Zuva API.

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

Base URLs

Request URLs are composed of the Zuva API 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 Zuva 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 Zuva 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 Zuva API 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 Zuva 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 Zuva API.

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"
  ],
  "options": {
    "field_heuristics": {
      "25d677a1-70d0-43c2-9b36-d079733dd020": true,
      "98086156-f230-423c-b214-27f542e72708": true,
      "fc5ba010-671b-427f-82cb-95c02d4c704c": true
    }
  }
}'

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"
  ],
  "options": {
    "field_heuristics": {
      "25d677a1-70d0-43c2-9b36-d079733dd020": true,
      "98086156-f230-423c-b214-27f542e72708": true,
      "fc5ba010-671b-427f-82cb-95c02d4c704c": true
    }
  }
}
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:

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 Description
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 Description
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"
  ],
  "options": {
    "field_heuristics": {
      "25d677a1-70d0-43c2-9b36-d079733dd020": true,
      "98086156-f230-423c-b214-27f542e72708": true,
      "fc5ba010-671b-427f-82cb-95c02d4c704c": true
    }
  }
}
Name Type Required Description
field_ids [string] true
file_ids [string] true
options ExtractionOptions false

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 Description
value string true
symbol string true
precision integer true

DateValues

Properties

{
  "day": 28,
  "month": 11,
  "year": 2022
}
Name Type Required Description
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 Description
file_id string true
field_ids [string] true
request_id string true
status StatusEnum true

ExtractionOptions

Properties

{
  "field_heuristics": {
    "25d677a1-70d0-43c2-9b36-d079733dd020": true,
    "98086156-f230-423c-b214-27f542e72708": true,
    "fc5ba010-671b-427f-82cb-95c02d4c704c": true
  }
}
Name Type Required Description
field_heuristics object false
» additionalProperties boolean false

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 Description
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 Description
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 Description
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 Description
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
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 Description
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 Description
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 Description
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 Description
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 Description
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 Description
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 Description
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 Description
index integer false
spans [Spans] false
issue_type string false

Spans

Properties

{
  "end": 0,
  "start": 0,
  "label": 0
}
Name Type Required Description
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 Description
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 Description
error HttpError false
field_id string true
request_id string true
status StatusEnum true
span_issues SpanIssues false