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
Japan	https://japan.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>

Name	In	Type	Required	Description
X-Attr-OCR	header	OcrTypeEnum	false	The type of OCR operation to perform on the file
X-Attr-MSWord-GenerateImages	header	string	false	Indicates whether to generate page images for MS Word documents when performing OCR
body	body	string(binary)	true	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	Meaning	Schema	Description
201	Created	FileCreatedResponse	The file was uploaded successfully
400	Bad Request	HttpError	A required header was not specified, or contained an invalid value
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	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	Required	Description
file_id	query	array[string]	true	File ID

Responses

Example responses

200 Response

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

Status	Meaning	Schema	Description
200	OK	DeleteFileStatusArray	The status of each deletion request.
400	Bad Request	HttpError	Invalid request
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	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	Required	Description
file_id	path	string	true	File ID

Responses

Status	Meaning	Schema	Description
204	No Content	None	The file was deleted successfully.
400	Bad Request	HttpError	Invalid file ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	File not found.
410	Gone	HttpError	File expired
500	Internal Server Error	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	Required	Description
file_id	path	string	true	File ID
Expiration	header	string	false	Expiration time for the file

Responses

Example responses

200 Response

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

Status	Meaning	Schema	Description
200	OK	FileUpdatedResponse	The file was updated successfully.
400	Bad Request	HttpError	Invalid file ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	File not found.
500	Internal Server Error	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	Required	Description
body	body	CreateExtractionRequestsBody	true	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	Meaning	Schema	Description
202	Accepted	ExtractionRequestsAccepted	See response body for status of each request.
400	Bad Request	HttpError	Malformed request, missing/invalid `file_ids` or `field_ids` attribute.
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	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	Required	Description
request_id	path	string	true	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	Meaning	Schema	Description
200	OK	ExtractionRequestStatus	The status of the extraction request
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
500	Internal Server Error	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	Required	Description
request_id	path	string	true	Request ID

Responses

Example responses

200 Response

{
  "file_id": "cdcpbqd9j3v1l06vsds0",
  "request_id": "cdcpcgt9j3va54jmj4b0",
  "results": [
    {
      "extractions": [
        {
          "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
              },
              "start": 632
            }
          ],
          "text": "LEASE"
        }
      ],
      "field_id": "668ee3b5-e15a-439f-9475-05a21755a5c1"
    }
  ]
}

Status	Meaning	Schema	Description
200	OK	GetExtractionTextResultResponse	The text result of an extraction
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
409	Conflict	HttpError	Results not ready yet
500	Internal Server Error	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	Required	Description
request_id	query	array[string]	true	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	Meaning	Schema	Description
200	OK	ExtractionStatuses	The status of multiple extraction requests
400	Bad Request	HttpError	Invalid request
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
500	Internal Server Error	HttpError	Internal Server Error

Document Classification

Find out what type of documents you have — whether they're contracts or not, and what type of contracts (or non-contract documents) they are.

Create classification requests

Code sample

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

POST /classification

Creates a new document classification request for each of the specified files.

Parameters

Body parameter

{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

Name	In	Type	Required	Description
body	body	CreateClassificationRequest	true	The file IDs to create classification 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	Meaning	Schema	Description
202	Accepted	ClassificationRequestsAccepted	See response body for status of each request.
400	Bad Request	HttpError	Malformed request or missing/invalid `file_ids` attribute.
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	HttpError	Internal Server Error

Get classification request

Code sample

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

GET /classification/{request_id}

Retrieves the status of a document classification request and, if the status is complete, its results.

Parameters

Name	In	Type	Required	Description
request_id	path	string	true	Request ID

Responses

Example responses

The status and results of the document classification request.

{
  "file_id": "c5e407f1qk1er7odm6tg",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete",
  "is_contract": true,
  "classification": "Real Estate Agt"
}

400 Response

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

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

Get classification requests

Code sample

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

GET /classifications

Retrieves the status of one or more document classification status requests. Each request ID should be provided as a query parameter, e.g. /classifications?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	Required	Description
request_id	query	array[string]	true	Classification 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",
      "classification": "Real Estate Agt",
      "is_contract": true
    }
  }
}

Status	Meaning	Schema	Description
200	OK	ClassificationStatuses	The status of multiple document classification requests
400	Bad Request	HttpError	Invalid request
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	HttpError	Internal Server Error

Language Classification

Find out the primary language of your documents.

Create language requests

Code sample

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

POST /language

Creates a new language classification request for each of the specified files, returning one request for each file.

Parameters

Body parameter

{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

Name	In	Type	Required	Description
body	body	CreateLanguageRequestsBody	true	The file IDs to create classification 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	Meaning	Schema	Description
202	Accepted	LanguageRequestsAccepted	See response body for status of each request.
400	Bad Request	HttpError	Malformed request, missing/invalid `file_ids` attribute.
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	HttpError	Internal Server Error

Get language request

Code sample

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

GET /language/{request_id}

Retrieves the status of a language classification request and, if the status is complete, its results.

Parameters

Name	In	Type	Required	Description
request_id	path	string	true	Request ID

Responses

Example responses

The status and results of the language classification request.

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

400 Response

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

Status	Meaning	Schema	Description
200	OK	LanguageStatus	The status and results of the language classification request.
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
500	Internal Server Error	HttpError	Internal Server Error

Get language requests

Code sample

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

GET /languages

Retrieves the status of one or more language classification status requests. Each request ID should be provided as a query parameter, e.g. /languages?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	Required	Description
request_id	query	array[string]	true	Language 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",
      "language": "English"
    }
  }
}

Status	Meaning	Schema	Description
200	OK	LanguageStatuses	The status of multiple language classification requests
400	Bad Request	HttpError	Invalid request
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	HttpError	Internal Server Error

Multi-Level Classification (MLC)

(In Alpha) 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	Required	Description
body	body	CreateMLCRequest	true	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	Meaning	Schema	Description
202	Accepted	MLCRequestsAccepted	See response body for status of each request.
400	Bad Request	HttpError	Malformed request or missing/invalid `file_ids` attribute.
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	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	Required	Description
request_id	path	string	true	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"
  ]
}

400 Response

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

Status	Meaning	Schema	Description
200	OK	MLCStatus	The status and results of the document classification request.
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
500	Internal Server Error	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	Required	Description
request_id	query	array[string]	true	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	Meaning	Schema	Description
200	OK	MLCStatuses	The status of multiple MLC requests
400	Bad Request	HttpError	Invalid request
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	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	Required	Description
body	body	NormalizeCurrencyRequestBody	true	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	Meaning	Schema	Description
200	OK	NormalizeCurrencyResponseBody	See response body for status of request.
400	Bad Request	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	Required	Description
body	body	NormalizeDateRequestBody	true	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	Meaning	Schema	Description
200	OK	NormalizeDateResponseBody	See response body for status of request.
400	Bad Request	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	Required	Description
body	body	NormalizeDurationRequestBody	true	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	Meaning	Schema	Description
200	OK	NormalizeDurationResponseBody	See response body for status of request.
400	Bad Request	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	Required	Description
body	body	CreateOcrRequestsBody	true	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	Meaning	Schema	Description
202	Accepted	OcrRequestsAccepted	See response body for status of each request.
400	Bad Request	HttpError	Malformed request, missing/invalid `fileIds` attribute.
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	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	Required	Description
request_id	path	string	true	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	Meaning	Schema	Description
200	OK	OcrRequestStatus	The status of an OCR request
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
500	Internal Server Error	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	Required	Description
request_id	query	array[string]	true	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	Meaning	Schema	Description
200	OK	OCRStatuses	The status of multiple OCR requests
400	Bad Request	HttpError	Invalid request
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
500	Internal Server Error	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	Required	Description
request_id	path	string	true	Request ID

Responses

Status	Meaning	Schema	Description
200	OK	string	eOCR document was retrieved successfully.
204	No Content	None	No content of this type was found.
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
409	Conflict	HttpError	OCR results not ready yet
500	Internal Server Error	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	Required	Description
request_id	path	string	true	Request ID

Responses

Status	Meaning	Schema	Description
200	OK	string	Images were retrieved successfully.
204	No Content	None	No content of this type was found.
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
409	Conflict	HttpError	OCR results not ready yet
500	Internal Server Error	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	Required	Description
request_id	path	string	true	Request ID
page_number	path	integer	true	Page Number

Responses

Status	Meaning	Schema	Description
200	OK	string	Image was retrieved successfully.
204	No Content	None	No content of this type was found.
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
409	Conflict	HttpError	OCR results not ready yet
500	Internal Server Error	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	Required	Description
request_id	path	string	true	Request ID

Responses

Status	Meaning	Schema	Description
200	OK	string	Layouts were retrieved successfully.
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
409	Conflict	HttpError	OCR results not ready yet
500	Internal Server Error	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	Required	Description
request_id	path	string	true	Request ID

Responses

Example responses

200 Response

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

Status	Meaning	Schema	Description
200	OK	OcrTextResponse	The OCR text result
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
409	Conflict	HttpError	OCR results not ready yet
500	Internal Server Error	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	Meaning	Schema	Description
200	OK	FieldListResponse	List of fields with metadata.
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
500	Internal Server Error	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",
  "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",
  "field_name": "My New Field",
  "from_field_id": "12345678-1234-1234-1234-123456789012"
}

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

Responses

Example responses

201 Response

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

Status	Meaning	Schema	Description
201	Created	NewFieldResponse	ID of newly created field
400	Bad Request	HttpError	Specified `from_field_id` does not exist
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
500	Internal Server Error	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	Required	Description
field_id	path	string	true	Field ID

Responses

Example responses

200 Response

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

Status	Meaning	Schema	Description
200	OK	FieldAccuracyResponse	The field's accuracy
400	Bad Request	HttpError	Invalid field ID
404	Not Found	HttpError	Field not found.
409	Conflict	HttpError	The field has not finished training yet
500	Internal Server Error	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	Required	Description
field_id	path	string	true	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	Meaning	Schema	Description
200	OK	FieldMetadataResponse	The field's metadata
400	Bad Request	HttpError	Invalid field ID
404	Not Found	HttpError	Field not found.
500	Internal Server Error	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	Required	Description
field_id	path	string	true	Field ID
body	body	PutFieldMetadataRequest	true	The updated metadata for the field

Responses

Status	Meaning	Schema	Description
204	No Content	None	The metadata for the field was successfully updated
400	Bad Request	HttpError	Invalid field ID
404	Not Found	HttpError	Field not found.
405	Method Not Allowed	HttpError	Cannot update a read-only field
500	Internal Server Error	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.

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

Parameters

Name	In	Type	Required	Description
field_id	path	string	true	Field ID

Responses

Example responses

200 Response

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

Status	Meaning	Schema	Description
200	OK	FieldValidationDetailsResponse	The field's validation details
400	Bad Request	HttpError	Invalid field ID
404	Not Found	HttpError	Field not found.
409	Conflict	HttpError	A training request is in progress for this field
500	Internal Server Error	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	Required	Description
field_id	path	string	true	Field ID
body	body	FieldTrainingRequest	true	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	Meaning	Schema	Description
202	Accepted	TrainingRequestStatus	The status of the training request
400	Bad Request	HttpError	Invalid request body
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Field not found.
409	Conflict	HttpError	Conflict: training request ongoing
500	Internal Server Error	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	Required	Description
field_id	path	string	true	Field ID
request_id	path	string	true	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	Meaning	Schema	Description
200	OK	TrainingRequestStatus	The status of the training request
400	Bad Request	HttpError	Invalid request ID
401	Unauthorized	HttpError	Unauthorized
403	Forbidden	HttpError	Forbidden
404	Not Found	HttpError	Request not found.
500	Internal Server Error	HttpError	Internal Server Error

Schemas

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
  },
  "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
start	integer	true

ClassificationPercentage

Properties

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

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

ClassificationRequestsAccepted

Properties

{
  "file_ids": [
    {
      "classification": "Real Estate Agt",
      "error": {
        "code": "http-error",
        "message": "Something went wrong, please try again later."
      },
      "file_id": "c5e407f1qk1er7odm6tg",
      "is_contract": true,
      "request_id": "c5e463f1qk154j5e3sjg",
      "status": "complete"
    }
  ]
}

Name	Type	Required	Description
file_ids	[ClassificationStatus]	true

ClassificationStatus

Properties

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

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

ClassificationStatuses

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",
      "classification": "Real Estate Agt",
      "is_contract": true
    }
  }
}

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

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".

CreateClassificationRequest

Properties

{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

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

CreateExtractionRequestsBody

Properties

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

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

CreateLanguageRequestsBody

Properties

{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

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

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

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

ExtractionRequestStatus

Properties

{
  "error": {
    "code": "http-error",
    "message": "Something went wrong, please try again later."
  },
  "field_ids": [
    "c83868ae-269a-4a1b-b2af-c53e5f91efca"
  ],
  "file_id": "c5e407f1qk1er7odm6tg",
  "request_id": "c5e463f1qk154j5e3sjg",
  "status": "complete"
}

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

ExtractionRequestsAccepted

Properties

{
  "file_ids": [
    {
      "error": {
        "code": "http-error",
        "message": "Something went wrong, please try again later."
      },
      "field_ids": [
        "c83868ae-269a-4a1b-b2af-c53e5f91efca"
      ],
      "file_id": "c5e407f1qk1er7odm6tg",
      "request_id": "c5e463f1qk154j5e3sjg",
      "status": "complete"
    }
  ]
}

Name	Type	Required	Description
file_ids	[ExtractionRequestStatus]	true

ExtractionResult

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

Properties

{
  "extractions": [
    {
      "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
          },
          "start": 632
        }
      ],
      "text": "LEASE"
    }
  ],
  "field_id": "668ee3b5-e15a-439f-9475-05a21755a5c1"
}

Name	Type	Required	Description
extractions	[TextExtraction]	true	[A `Result` contains an array of all extractions of a field from the file.]
field_id	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

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


tp
fn
fp

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

GetExtractionTextResultResponse

Properties

{
  "file_id": "cdcpbqd9j3v1l06vsds0",
  "request_id": "cdcpcgt9j3va54jmj4b0",
  "results": [
    {
      "extractions": [
        {
          "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
              },
              "start": 632
            }
          ],
          "text": "LEASE"
        }
      ],
      "field_id": "668ee3b5-e15a-439f-9475-05a21755a5c1"
    }
  ]
}

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.]

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

LanguageRequestsAccepted

Properties

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

Name	Type	Required	Description
file_ids	[LanguageStatus]	true

LanguageStatus

Properties

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

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

LanguageStatuses

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",
      "language": "English"
    }
  }
}

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

Location

Properties

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

Name	Type	Required	Description
end	integer	true
start	integer	true

MLCRequestsAccepted

Properties

{
  "file_ids": [
    {
      "classifications": [
        "string"
      ],
      "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"
  ],
  "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
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


auto
ocr
msword
text
eocr

PostFieldRequest

Properties

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

Name	Type	Required	Description
description	string	false
field_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

StatusEnum

string

Enumerated Values


queued
processing
complete
failed

TextExtraction

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

Properties

{
  "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
      },
      "start": 632
    }
  ],
  "text": "LEASE"
}

Name	Type	Required	Description
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"
}

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