NAV

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.

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.

Files are deleted from the system after 48 hours. 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
body body string(binary) true The file content

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

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 status

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 multiple extraction statuses

Code sample

curl https://us.app.zuva.ai/api/v2/extractions?request_id={id_1}&request_id={id_2} \
     -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 100 request IDs can be included in a single query.

Parameters

Name In Type Required Description
request_id query string true Request ID

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 GetMultipleExtractionsResponse 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 status

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

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 status

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

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 status

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

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

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 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,
    "f_score": 0,
    "field_id": "12345678-1234-1234-1234-123456789012",
    "file_ids": [
      "c5e407f1qk1er7odm6tg"
    ],
    "is_custom": true,
    "is_trained": true,
    "name": "Field Name",
    "precision": 0,
    "recall": 0
  }
]
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",
  "field_id": "12345678-1234-1234-1234-123456789012",
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ],
  "is_trained": true,
  "name": "string",
  "read_only": true
}
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:

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 a field 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": [
      {
        "end": 456,
        "start": 123
      }
    ]
  }
]'

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": [
      {
        "end": 456,
        "start": 123
      }
    ]
  }
]
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 status

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 Description
bottom integer true
left integer true
right integer true
top integer true

BoundingBoxesByPage

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 BoundingBox false Deprecated. Please use bboxes instead.
bboxes [BoundingBoxesByPage] true
end integer true
pages Span true
start integer 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 Description
classification string false
error HttpErrorDetails false
file_id string true
is_contract boolean false
request_id string true
status StatusEnum true

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.

CreateOcrRequestsBody

Properties

{
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ]
}

Name Type Required Description
file_ids [string] 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 Description
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

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,
    "f_score": 0,
    "field_id": "12345678-1234-1234-1234-123456789012",
    "file_ids": [
      "c5e407f1qk1er7odm6tg"
    ],
    "is_custom": true,
    "is_trained": true,
    "name": "Field Name",
    "precision": 0,
    "recall": 0
  }
]

Name Type Required Description
anonymous [FieldListResponseElement] false

FieldListResponseElement

Properties

{
  "bias": 0,
  "description": "Description of the field.",
  "document_count": 0,
  "f_score": 0,
  "field_id": "12345678-1234-1234-1234-123456789012",
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ],
  "is_custom": true,
  "is_trained": true,
  "name": "Field Name",
  "precision": 0,
  "recall": 0
}

Name Type Required Description
bias number true
description string true
document_count integer true
f_score number true
field_id string true
file_ids [string] true
is_custom boolean true
is_trained boolean true
name string true
precision number true
recall number true

FieldMetadataResponse

Properties

{
  "description": "string",
  "field_id": "12345678-1234-1234-1234-123456789012",
  "file_ids": [
    "c5e407f1qk1er7odm6tg"
  ],
  "is_trained": true,
  "name": "string",
  "read_only": true
}

Name Type Required Description
description string true
field_id string true
file_ids [string] true
is_trained boolean true
name string true
read_only boolean true

FieldTrainingRequest

Properties

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

Name Type Required Description
file_id string 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

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

GetMultipleExtractionsResponse

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

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.

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 Description
error HttpErrorDetails false
file_id string true
language string false
request_id string true
status StatusEnum true

Location

Properties

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

Name Type Required Description
end integer true
start integer true

NewFieldResponse

Properties

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

Name Type Required Description
field_id string false

OcrRequestStatus

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

OcrRequestsAccepted

Properties

{
  "file_ids": [
    {
      "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 [OcrRequestStatus] true

OcrTextResponse

Properties

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

Name Type Required Description
request_id string true
text string true

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 Description
error HttpError false
field_id string true
request_id string true
status StatusEnum true