Skip to content
Sourcebox API Reference


The document to be processed must be passed along with login information and any other data to the Sourcebox Extract! service as an HTTP POST multipart request with content type multipart/form-data at the following URLs:

Note: The URL prefix ( in the example) may be different for you. Please check with your Textkernel consultant.

Extract service🔗

The request contains at least the following form parameters:

Parameter Description Parameter MIME type
uploaded_file the binary file data of the document to be processed see note below
account the account name of the user text/plain
username the username of the user text/plain
password the password of the user text/plain

Required Extract service HTTP POST parameters

!!! note The content of 'uploaded_file' must be the raw document. The Content-Type (MIME type) of the file is automatically detected by Extract and so can simply be 'application/octet-stream'.

On success, the request returns the templated result. The output can be in XML or JSON depending on the pipeline configuration. Section Error Handling below explains Sourcebox behaviour in case of error.

See below for a simple curl example for processing the file 'petra.doc':

curl \
      --form account=exampleaccount \
      --form username=exampleuser \
      --form password=examplepassword \
      --form uploaded_file=@/home/user/petra.doc  

Error Handling (🔗

By default, in case of error, the Extract service returns an HTML error page with HTTP status 200. Information about the error and error description is included in the title section of the HTML, in the meta tags error-code and error-desc.

Alternatively, it is possible to enable HTTP protocol compliance, by adding useHttpErrorCodes=true to the POST URL. It is also possible to return error information as a JSON string by adding parameter useJsonErrorMsg=true to the POST URL. Note that useJsonErrorMsg=true implies useHttpErrorCodes=true.

To enable both JSON error messages and HTTP status compliance, POST to:


To only enable HTTP status compliance, POST to:


Sourcebox Error Codes🔗

General Errors

Error Code Description
DEFAULT_EXCEPTION An unexpected exception occurred.
UNSUPPORTED_OPERATION_ERROR The requested method is not supported by Sourcebox.

Access Errors

Error Code Description
INVALID_CREDENTIALS_ERROR The login credentials are invalid.
LIMIT_EXCEEDED The allotted amount of usable processing units for the account has been exceeded.
NO_ACCESS The resource is not visible to the user with the given credentials.
SESSION_INVALID The session related to the users cookie has already been invalidated.
TRXML_LOCKED The document cannot be accessed because it is currently edited by another user/process.

Configuration Errors

Error Code Description
CODETABLE_ERROR Sourcebox encountered a malformed code table or could not upload the code table to the normalizer.
CONFIGURATION_ERROR The configuration for the account or user is invalid.
MODEL_FILE_INVALID The model file contains invalid configuration options or the XML is not well formed.

Email Errors

Error Code Description
EMAIL_PARSING_ERROR An error occurred processing an email.
EMAIL_SENDING_ERROR An error occurred when Sourcebox attempted to send an email.
TEMPLATE_FORMAT_ERROR An email template could not be processed.
TEMPLATE_READING_ERROR An email template could not be found in the templater configured for the account.

Product Errors

Error Code Description
AGENT_ERROR Sourcebox could not download or process a URL.
EXTERNAL_SYSTEM_ERROR A request issued from Sourcebox to an external system could not be completed.
HTTP_ERROR When communicating with an external system via HTTP an HTTP error occurred.
OAUTH_ERROR An error occured when trying to retrieve a resource protected by OAUTH.
STORE_ERROR The templating result could not be stored with the configured exportmethod (product).

Sourcebox Internal Errors

Error Code Description
DATABASE_ERROR An error occurred when accessing the Sourcebox database.
TRXML_INVALID The document cannot be edited because it has become corrupted.
TRXML_RETRIEVAL_ERROR The current trxml cannot be edited because it is corrupted.
IO_ERROR Sourcebox could not access a resource on the file system.

OCR Errors

Error Code Description
OCR_ERROR An error occurred when processing an image with OCR functionality.
INVALID_HIGHLIGHT_COORDINATES Highlights for a OCRed document as returned from textractor cannot be parsed.

Processing Errors

Error Code Description
ATOMIC_POST_ERROR An unexpected error occurred when processing the HTTP POST request.
FILE_UPLOAD_ERROR An error occurred processing a file upload request.
TEXTRACTOR_ERROR A textractor error occurred when processing a document.
ENCODING_ERROR A code table or a trxml contains a byte sequence that is not UTF-8 encoded.
MIME_TYPE_MISSING The mime type of the uploaded document could not be determined from the document or was missing from the request.
INPUT_MISSING A required parameter has been omitted from a request.
INVALID_INPUT A required parameter contains a invalid value.
PROCESSING_INPUT_MISSING No data were received from textractor.
REPROCESSING_ERROR An error occurred when reprocessing an already processed document.
VALIDATION_ERROR The document is invalid according to the validation rules configured in the model file.
REQUEST_LIMIT_EXCEEDED Too many processing requests are being executed simultaneously by this account.

TMF Errors

Error Code Description
TMF_MERGE_ERROR The supplied TMF could not be merged into the document.
TMF_VALIDATION_ERROR The supplied TMF does not conform to the TMF XSD.

UI Errors

Error code Description
AJAX_ERROR An Ajax request from the CV editing UI caused an error.
EDITING_ERROR A error occurred when editing a trxml document in the Sourcebox user interface.


In this section, some common HTML error messages associated with requests to the HTTP POST Extract service are clarified.

Authentication error🔗

Message: Page requires authentication (401). Access denied at login.

Solution: Make sure you are using the correct Sourcebox URL and provide a valid account/user/password combination.

Empty document🔗

Message: com.textkernel.txtor_ui.actions.ActionException: Error occurred while processing atomic post: No suitable processing strategy exists for this request!

Solution: Submit a document that is not empty.

Unsupported document type🔗

Message: com.textkernel.txtor_ui.actions.ActionException: Error occurred while processing atomic post: Preprocessing failed; ERROR: 500 Failed to convert document of type ...

Solution: An unsupported document type was submitted.