Coming up Soon

This function has not been implemented yet.

Follow us to get updates on ContractWorkBox.

API

API Reference

Welcome

Welcome to ContractWorkBox API, a software layer that allows your platform/application to interact with ContractWorkBox. The platform is designed to provide document navigation and translation functionalities and integrate them in your system. The API functions support common tasks and operations such as user authentication and logout, document upload and structure identification, document opening with ContractWorkBox Smart View, etc. .

Each API Endpoint supports both the REST and RPC Endpoint formats.

The default endpoint response format is JSON unless otherwise specified.

REST reference

The Endpoints in REST format are reported below.

Authorization

Registered users can login to establish their identity and start a session with the application using the API below. The Application KEY required in the authentication process may be requested from the Request APP Key form.

Endpoint format
REST
Method
POST
URL Structure
https://www.contractworkbox.com/api/gkp/users/authorize
Request Body
app_key=app_key_id

Where:

ArgumentDescription
app_key_id
String
The Application KEY you are provided when you register to the ContractWorkBox API service.
Request Example
curl https://www.contractworkbox.com/api/gkp/users/authorize \ -d "app_key=ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKL"
Response
The response body contains data with the following structure:
{ "error": 0, "message_key": "logged_in", "hash": "s15VNW7lULfe3VQ176DzgfdY74XtTBvJyjmiySv246Rqt2Y2zbrqrMwvscMyvQsv", "expire": 1609574347, "availSpace": 200, "trCredits": 1000000, "usedSpace": 1207744 }

Where:

ArgumentDescription
error
Int
The result of the Authentication. If correctly authenticated, then 0 (zero) is returned.
message_key
String
A human-readable description of the Authentication result.
hash
String
A temporary access TOKEN to be used in the API requests.
expire
Int (Timestamp)
The expire datetime of the session.
availSpace
Int
The total available space (in MB).
trCredits
Int
The Translation Credits available to be consumed.
usedSpace
Int
The space used (in Bytes).

Logout

The Logout operation terminates user session and disassociates the authenticated user from the subsequent requests made by the client application.

Endpoint format
REST
Method
GET
URL Structure
https://www.contractworkbox.com/api/gkp/users/logout
Request Headers
Authorization: Bearer hash

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Example
curl -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ https://www.contractworkbox.com/api/gkp/users/logout
Response
The response body contains data with the following structure:
{ "result": "Logout successful" }

Document Upload

The document file upload operation delivers and saves a local file in the remote ContractWorkBox file storage. The document is then automatically processed by ContractWorkBox.

Endpoint format
REST
Method
POST
URL Structure
https://www.contractworkbox.com/api/gkp/documents
Request Headers
Authorization: Bearer hash Content-Type: multipart/form-data

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Body
file=@path_to_file

Where:

ArgumentDescription
path_to_file
String
The path to the file to be uploaded.
Request Example
curl -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ -H "Content-Type: multipart/form-data" \ -F "file=@/tmp/Professional\ Services\ Agreement\ US.pdf" \ https://www.contractworkbox.com/api/gkp/documents
Response
The response body contains data with the following structure:
{ "fileId": "QhWv1F/y3Wku", "filename": "Professional Services Agreement US", "created": "1577359648" "availSpace": 200, "usedSpace": 8114173 }

Where:

ArgumentDescription
fileId
String
A unique Identifier for the document.
filename
String
The Name of the document file.
created
Int (Timestamp)
The date/time of the document's upload.
availSpace
Int
The total available space (in MB).
usedSpace
Int
The space used (in Bytes).

Deleting a Document

The "Delete" operation deletes a Document previously uploaded.

Endpoint format
REST
Method
DELETE
URL Structure
https://www.contractworkbox.com/api/gkp/documents/fileId

Where:

ArgumentDescription
fileId
String
The unique Identifier for the document file to be deleted.
Request Headers
Authorization: Bearer hash

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Example
curl -X DELETE \ -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ https://www.contractworkbox.com/api/gkp/documents/QhWv1F/y3Wku
Response
The response body contains data with the following structure:
{ "availSpace": 200, "usedSpace": 8114173 }

Where:

ArgumentDescription
availSpace
Int
The total available space (in MB).
usedSpace
Int
The space used (in Bytes) after that the document is deleted.

Getting Open URL

The "Open URL" operation retrieves an URL that can be utilized to navigate a document previously uploaded with the ContractWorkBox Smart View.

Endpoint format
REST
Method
GET
URL Structure
https://www.contractworkbox.com/api/gkp/documents/fileId/url

Where:

ArgumentDescription
fileId
String
The unique Identifier for the document file to be deleted.
Request Headers
Authorization: Bearer hash

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Example
curl -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ https://www.contractworkbox.com/api/gkp/documents/QhWv1F/y3Wku/url
Response
The response body contains data with the following structure:
{ "url": "https://www.contractworkbox.com/ (...)" }

Where:

ArgumentDescription
url
String
A URL that can be utilized to access the document from a browser.

Opening a Document

The "Open Document" operation is a shortcut for opening a previously uploaded document directly from the browser, without getting the Open URL. The response format, if the operation is successful, is a ContractWorkBox Smart View HTML page showing the document.

Endpoint format
REST
Method
GET
URL Structure
https://www.contractworkbox.com/api/gkp/documents/fileId/open?hash=hash

Where:

ArgumentDescription
fileId
String
The unique Identifier for the document file to be deleted.
hash
String
The temporary access TOKEN returned by the Authentication.
Request Example
window.open( "https://www.contractworkbox.com/api/gkp/documents/QhWv1F/y3Wku/open?hash=uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1", "_blank" )

Document List

The "Document List" operation lists all the document uploaded.

Endpoint format
REST
Method
GET
URL Structure
https://www.contractworkbox.com/api/gkp/documents
Request Headers
Authorization: Bearer hash

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Example
curl -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ https://www.contractworkbox.com/api/gkp/documents
Response
The response body contains data with the following structure:
{ "documents": [ { "fileId": "QhWv1F/iYdEY", "filename": "Life Insurance Conditions", "name": "General Conditions", "modified": "1576943941", "created": "1576943941" }, { "fileId": "QhWv1F/y3Wku", "filename": "Professional Services Agreement US", "name": "Professional Services Agreement", "modified": "1577359648", "created": "1577359648" } ], "nDocuments": "2" }

Where:

ArgumentDescription
documents
Array
The list of the documents uploaded. Each element of the Array is an Object corresponding to a document, with the fields described as following.
fileId
String
A unique Identifier for the document.
filename
String
The Name of the document file.
name
String
The Title of the document.
modified
Int (Timestamp)
The date/time of the last modification.
created
Int (Timestamp)
The date/time of the document's upload.
nDocuments
Int
The number of the documents returned (must be equal to the length of the Array "documents").

RPC reference

The Endpoints in RPC format are reported below.

Authorization

Registered users can login to establish their identity and start a session with the application using the API below. The Application KEY required in the authentication process may be requested from the Request APP Key form.

Endpoint format
RPC
Method
POST
URL Structure
https://www.contractworkbox.com/api/gkp/authorize
Request Body
app_key=app_key_id

Where:

ArgumentDescription
app_key_id
String
The Application KEY you are provided when you register to the ContractWorkBox API service.
Request Example
curl https://www.contractworkbox.com/api/gkp/authorize \ -d "app_key=ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKL"
Response
The response body contains data with the following structure:
{ "error": 0, "message_key": "logged_in", "hash": "s15VNW7lULfe3VQ176DzgfdY74XtTBvJyjmiySv246Rqt2Y2zbrqrMwvscMyvQsv", "expire": 1609574347, "availSpace": 200, "trCredits": 1000000, "usedSpace": 1207744 }

Where:

ArgumentDescription
error
Int
The result of the Authentication. If correctly authenticated, then 0 (zero) is returned.
message_key
String
A human-readable description of the Authentication result.
hash
String
A temporary access TOKEN to be used in the API requests.
expire
Int (Timestamp)
The expire datetime of the session.
availSpace
Int
The total available space (in MB).
trCredits
Int
The Translation Credits available to be consumed.
usedSpace
Int
The space used (in Bytes).

Logout

The Logout operation terminates user session and disassociates the authenticated user from the subsequent requests made by the client application.

Endpoint format
RPC
Method
GET
URL Structure
https://www.contractworkbox.com/api/gkp/logout
Request Headers
Authorization: Bearer hash

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Example
curl -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ https://www.contractworkbox.com/api/gkp/logout
Response
The response body contains data with the following structure:
{ "result": "Logout successful" }

Document Upload

The document file upload operation delivers and saves a local file in the remote ContractWorkBox file storage. The document is then automatically processed by ContractWorkBox.

Endpoint format
RPC
Method
POST
URL Structure
https://www.contractworkbox.com/api/gkp/upload_document
Request Headers
Authorization: Bearer hash Content-Type: multipart/form-data

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Body
file=@path_to_file

Where:

ArgumentDescription
path_to_file
String
The path to the file to be uploaded.
Request Example
curl -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ -H "Content-Type: multipart/form-data" \ -F "file=@/tmp/Professional\ Services\ Agreement\ US.pdf" \ https://www.contractworkbox.com/api/gkp/upload_document
Response
The response body contains data with the following structure:
{ "fileId": "QhWv1F/y3Wku", "filename": "Professional Services Agreement US", "created": "1577359648" "availSpace": 200, "usedSpace": 8114173 }

Where:

ArgumentDescription
fileId
String
A unique Identifier for the document.
filename
String
The Name of the document file.
created
Int (Timestamp)
The date/time of the document's upload.
availSpace
Int
The total available space (in MB).
usedSpace
Int
The space used (in Bytes).

Deleting a Document

The "Delete" operation deletes a Document previously uploaded.

Endpoint format
RPC
Method
POST
URL Structure
https://www.contractworkbox.com/api/gkp/delete_document
Request Headers
Authorization: Bearer hash

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Body
id=fileId

Where:

ArgumentDescription
fileId
String
The unique Identifier for the document file to be deleted.
Request Example
curl -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ -d "id=QhWv1F/y3Wku" \ https://www.contractworkbox.com/api/gkp/delete_document
Response
The response body contains data with the following structure:
{ "availSpace": 200, "usedSpace": 8114173 }

Where:

ArgumentDescription
availSpace
Int
The total available space (in MB).
usedSpace
Int
The space used (in Bytes) after that the document is deleted.

Getting Open URL

The "Open URL" operation retrieves an URL that can be utilized to navigate a document previously uploaded with the ContractWorkBox Smart View.

Endpoint format
RPC
Method
GET
URL Structure
https://www.contractworkbox.com/api/gkp/get_document_url
Request Headers
Authorization: Bearer hash

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Body
id=fileId

Where:

ArgumentDescription
fileId
String
The unique Identifier for the document file to be deleted.
Request Example
curl -G -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ -d "id=QhWv1F/y3Wku" \ https://www.contractworkbox.com/api/gkp/get_document_url
Response
The response body contains data with the following structure:
{ "url": "https://www.contractworkbox.com/ (...)" }

Where:

ArgumentDescription
url
String
A URL that can be utilized to access the document from a browser.

Opening a Document

The "Open Document" operation is a shortcut for opening a previously uploaded document directly from the browser, without getting the Open URL. The response format, if the operation is successful, is a ContractWorkBox Smart View HTML page showing the document.

Endpoint format
RPC
Method
GET
URL Structure
https://www.contractworkbox.com/api/gkp/get_document_url
Request Body
id=fileId hash=hash

Where:

ArgumentDescription
fileId
String
The unique Identifier for the document file to be deleted.
hash
String
The temporary access TOKEN returned by the Authentication.
Request Example
window.open( "https://www.contractworkbox.com/api/gkp/open_document?id=QhWv1F/y3Wku&hash=uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1", "_blank" )

Document List

The "Document List" operation lists all the document uploaded.

Endpoint format
RPC
Method
GET
URL Structure
https://www.contractworkbox.com/api/gkp/list_documents
Request Headers
Authorization: Bearer hash

Where:

ArgumentDescription
hash
String
The temporary access TOKEN returned by the Authentication.
Request Example
curl -H "Authorization: Bearer uuIHtZxhVJXUWIyKmEBgdswTAizjCF2vss3XsLhZREkEPpXIuvTQmKBxUqdvcPK1 " \ https://www.contractworkbox.com/api/gkp/list_documents
Response
The response body contains data with the following structure:
{ "documents": [ { "fileId": "QhWv1F/iYdEY", "filename": "Life Insurance Conditions", "name": "General Conditions", "modified": "1576943941", "created": "1576943941" }, { "fileId": "QhWv1F/y3Wku", "filename": "Professional Services Agreement US", "name": "Professional Services Agreement", "modified": "1577359648", "created": "1577359648" } ], "nDocuments": "2" }

Where:

ArgumentDescription
documents
Array
The list of the documents uploaded. Each element of the Array is an Object corresponding to a document, with the fields described as following.
fileId
String
A unique Identifier for the document.
filename
String
The Name of the document file.
name
String
The Title of the document.
modified
Int (Timestamp)
The date/time of the last modification.
created
Int (Timestamp)
The date/time of the document's upload.
nDocuments
Int
The number of the documents returned (must be equal to the length of the Array "documents").

Error Codes

The most common error codes with an explanation of the possible causes are reported in the following table.

CodeError Message / Description
#E00
Generic Error
This error code is returned if more specific details on the error occurred are not available
#E01
Error Saving File
An error occurred while storing of the uploaded file to the ContractWorkBox cloud.
#E02
Error: Converted File too long
The size limit for the structure analyzed has been exceeded.
#E03
Error: Uploaded File too long
The size limit for the file uploaded has been exceeded.
#E04
Error: Cloud Space Limit overcome
The total space limit in the ContractWorkBox Cloud has been exceeded.
#E05
Error Processing PDF
An error occurred when converting the uploaded file into HTML.
#E06
Error: Too many PDF uploaded
The number limit of file uploads in 15 minutes has been exceeded.
#E07
Missing Converted File
The converted HTML file is missing.
#E08
Unable to creating directory
An error occurred when creating a directory in the ContractWorkBox server.
#E09
Error: Text Extraction from PDF not allowed
The content extraction of the PDF document uploaded is not allowed (SECURED document).
#E10
Signup Error
An error occurred in the user registration process.
#E07
Missing Original File
The uploaded file is missing in the ContractWorkBox server.
#E11
Error: Resource not found
The API resource/method cannot be found.
#E12
Error: Invalid or Missing App KEY
The App KEY is missing in the Authorization request.
#E14
Error: Account Not Active
The Account related to the App KEY is not active.
#E15
Error Logging Out
An error occurred in the logout process.
#E16
Error: Missing Parameters
One or more required parameters are missing in the API request.
#E19
Error Identifying Structure
An error occurred identifying the structure of the uploaded document.
#E20
Error Identifying Structure: Missing Section(s)
One or more (sub)sections are missing / could not have been identified in the uploaded document.
#E21
Error Identifying Structure: Section(s) Duplicated
One or more (sub)sections have been identified as duplicated in the uploaded document.
#E40
Error Translating
An error occurred translating the content of the document.
#E41
Error: Translation Credits exhausted
The Translation Credits exhausted in the Account.
#W01
Warning: Not Logged
Possible reasons of this error are: the hash is not valid, or the related session has expired.

Request APP Key

Notice
Message sent successfully!
Error

Error sending the message.

Please try again later.