Working with Files

To exchange files with the Application Server, use a POST request.

To use an API, you must first connect to a Web service.

Types of actions

With the help of POST requests the following actions can be executed:

  • Load files from server (Action = Load)
  • Save files on the server (Action = Save)
  • Append data to the end of the file (Action = Append)
  • Getting a checksum for a file from the server (checksum is calculated using the CRC32 method) (Action = Checksum)

Possible use

  1. Importing images. Loading image files, also by parts and getting the checksum.
  2. Getting original page images at any time of processing.
  3. Working with attachments of batches, documents, pages (upload / download).
    Note: For working with large attachments, POST requests should be used. Large files are divided into smaller parts and uploaded to server. If POST request is used to add an attachment to an object, the SaveAttachment method should be called after the POST request. As the file parameter of the SaveAttachment method, the zero-length file with the name of the transferred file is passed.
    In other cases, it is recommended to use methods which are specially developed for working with attachments.
  4. Getting XML description of the verification task, modifying this document and saving changes on the server.

Request parameters

Note: Make sure that the request fields are completed correctly.

Name Type Description
Action string

Type of action. Possible values:

  • Load loads a file from the server
  • Save saves a file on the server
  • Append appends data to an existing file on the server
  • Checksum requests a checksum for a file from the server; checksums are calculated using the CRC32 method
sessionId int Session ID (used for checking the user's permissions)
projectId int Project ID
batchId int Batch ID
objectType int

Type of object on the server. Possible values

  • 0 document
  • 1 page
  • 5 small copy of the page to be displayed as a thumbnail; PNG file
  • 8 task attachment (XML document)
    Note: Effective when working with large attachments. Otherwise, it is recommended to use methods which have been specifically developed for working with attachments.
  • 13 file accessible to all users (e.g. End-User License Agreement)
    Note:  For files of this type,  ProjectId=0 and BatchId=0, i.e. they do not belong to any particular project, batch or tenant. To write a file of this type, the administrator must open a session. To read a file of this type, pass sessionid=0 (there is no need to open a session).
objectId int Object ID (ID of a document, page, or task)
parentId int

The ID of the parent document

Note: The parameter is specified for document sets. For documents that are not part of a set, the recommended value is 0.

version int File version
streamName string

The name of the Base64-encoded binary stream when saving a file to the server, or of the UrlEncode-encoded binary stream when loading a file from the server. Possible values

for pages:

  • BlackWhiteImage the black-and-white image of the page; PNG file
  • ColorImage the color image of the page; JPG file
  • Preview page preview image; PNG file

for documents:

  • DocumentBody an XML document that describes document fields. Created when preparing the task for the Web-stations. After verification, the changes in the document are processed. Versions are not supported, the version parameter must be set to 0. Save the document processing results to this file.
  • Page pageID, where pageID is an ID of a page returned by the AddNewPage method. This stream name can be used to upload source page image before preprocessing.
  • FileName, where FileName is a name of a file specified when creating the document by the AddNewDocument method. This stream name can be used to upload a multi-page file with document page images.
  • RecognizedWords an XML document that contains recognized words and their coordinates on the page.

for tasks:

  • Verification an XML document that describes a verification task. Created when preparing the task for the Web-stations. After verification, the changes in the document are processed. Versions are not supported, the version parameter must be set to 1. Save the task processing results to this file.
  • VerificationRequest corresponds to any of the following requests:
    • an XML document that contains a request to execute operations within a batch, including document separation and page re-arrangement. In particular, this type of request is used by the Web Station for rule checks.
    • an XML document containing a routing request
    • an XML document containing a LineItems extrapolation request
    • an XML document containing a data verification request
blob Binary file data (if the Action parameter is set to Save or Append)
offset int The offset from the start of the file after which to append the data (if the Action parameter is set to Append)

File Storage contains all files of the project. The file name contains information about the type of object, its identifier, name of the stream in the form of: <object type>-<object id>-<stream name>version.

Files of pages (objectType = 1) contain copies of images while document files (objectType = 0) contain source images. Thus, you cannot change an image using the POST request with the parameter: objectType = 1.

Example requests

Loading a file from the server

Saving a file on the server

For more information about POST request examples, see Examples.

25.05.2023 7:55:02

Please leave your feedback about this article

Usage of Cookies. In order to optimize the website functionality and improve your online experience ABBYY uses cookies. You agree to the usage of cookies when you continue using this site. Further details can be found in our Privacy Notice.