Introduction

Welcome to the contract.fit API! You can use our API to access document activation endpoints.

We have language bindings in Shell, Python and JavaScript.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Quick start

#Please make sure  you assign the right value to the three variables below
DOMAIN="your_domain"
USERNAME="your_username"
PASSWORD="your_password"

PATH_TO_YOUR_FILE="path_to_your_file"

curl -X POST \
  https://${DOMAIN}/admin/documents/ \
  -u ${USERNAME}:${PASSWORD} \
  -H 'cache-control: no-cache' \
  -F file=@${PATH_TO_YOUR_FILE}

#You will need to input the below three variables to get started
domain = "domain"
username = "username"
password = "password"

import base64
import requests

url = "https://" + domain + "/admin/documents/"
path_to_your_file = "path_to_your_file"

b64_encoded_credentials = base64.b64encode(f'{username}:{password}'.encode('utf-8'))

headers = {
    'authorization': 'Basic ' + b64_encoded_credentials.decode('utf-8'),
    'cache-control': "no-cache"
    }

with open(path_to_your_file, 'rb') as file:
    response = requests.request("POST", url, files={'file': file}, headers=headers)

print(response.json())

var domain = "domain"
var username = "username"
var password = "password"

const axios = require("axios");
const fs = require("fs");
const FormData = require("form-data");

var path_to_your_file = "path_to_your_file";
var url = 'https://'+domain+'/admin/documents/';

const form = new FormData();
form.append('file', fs.createReadStream(path));

const options = {
    headers: {...form.getHeaders()},
    auth: {username, password},
};

return axios
    .post(url, form, options)
    .then((res) => console.log(res.data))
    .catch((err) => console.log(err));

You can start uploading your files right away using Basic authentication, which requires from you providing only your username and password. As a response you will get field and classification predictions for your file.

Authentication

Make sure to fill in the right values for domain, username and password

#Please make sure  you assign the right value to the three variables below
DOMAIN="your_domain"
USERNAME="your_username"
PASSWORD="your_password"

response=`curl -s -X POST \
  https://${DOMAIN}/admin/auth \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{"username":"'${USERNAME}'","password":"'${PASSWORD}'"}'`

token=`echo $response|jq -r '.authentication_token'`

#You will need to input the below three variables to get started
domain = "domain"
username = "username"
password = "password"

import requests

url = "https://"+domain+"/admin/auth"

payload = "{\"username\":\""+username+"\",\"password\":\""+password+"\"}"
headers = {
    'content-type': "application/json",
    'cache-control': "no-cache"
    }

print(headers)
print(payload)
response = requests.request("POST", url, data=payload, headers=headers)

token = None

if response.status_code == 200:
    token = response.json()['authentication_token']
else:
    print("Authentication not succeeded, exiting")
    sys.exit(1)

var domain = "domain"
var username = "username"
var password = "password"

var request = require("request");

var options = { method: 'POST',
  url: 'https://'+domain+'/admin/auth',
  headers:
   { 'cache-control': 'no-cache',
     'content-type': 'application/json' },
  body: { username: username, password: password },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  token = body.authentication_token;
});

The above command returns JSON structured like this:

{
  "authentication_code": "token"
}

contract.fit uses tokens to access the API. You can obtain a key through this API call based on your username and password.

contract.fit expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer token

This API call will allow you to retrieve such a token.

HTTP Request

POST https://yourdomain.contract-t.fit/admin/auth

Parameters

Parameter	Description
username	your username
password	your password

Inboxes

Inboxes allow us to group documents which belong together, e.g., they need to be reviewed by one specific team.

For this documentation, we assume that you have just one inbox, which has been created when your organization was created.

Should you wish to learn more about inboxes and projects, we refer to the Swagger documentation.

List the available inboxes

response_inbox=`curl -s -X GET \
  https://${DOMAIN}.contract-t.fit/admin/inboxes \
  -H 'authorization: Bearer '${TOKEN} \
  -H 'cache-control: no-cache'`

INBOX_ID=`echo $response_inbox|jq -r '.[0]["id"]'`

url = "https://contractfit1.contract-t.fit/admin/inboxes"

headers = {
    'authorization': "Bearer "+token,
    'cache-control': "no-cache",
    }

response = requests.request("GET", url, headers=headers)

inbox_id = response.json()[0]['id']

var options = { method: 'GET',
  url: 'https://'+domain+'/admin/inboxes',
  headers:
   { 'cache-control': 'no-cache',
     authorization: 'Bearer '+token },
     json:true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  var inbox_id = body[0]["id"];
});

The above command returns JSON structured like this:

[
  {
    "id": "yourInboxId",
    "name": "yourInboxName",
    "project": "yourProjectId"
  }
]

So far, you have uploaded documents to the default inbox. To facilitate teamwork and to be able to support different needs, you can send your document to a specific inbox. You can control access to an inbox on a fine-grained level and you can use different inboxes for different projects. Here, we will just fetch the id of the first inbox which you have access to. This will then allow you to post a document to that inbox and inspect the results.

HTTP Request

GET https://yourdomain.contract-t.fit/admin/inboxes

Documents

Now, we are ready to post a document to the inbox, using the obtained inbox_id.

Post a document

Please make sure to correctly set the path to the file you want to post

PATH_TO_YOUR_FILE="path_to_your_file"

curl -X POST \
  https://${DOMAIN}.contract-t.fit/admin/documents/${INBOX_ID} \
  -H 'authorization: Bearer '${TOKEN} \
  -H 'cache-control: no-cache' \
  -F file=@${PATH_TO_YOUR_FILE}

url = "https://" + domain + "/admin/documents/" + inbox_id
path_to_your_file = "path_to_your_file"

headers = {
    'authorization': "Bearer " + token,
    'cache-control': "no-cache"
    }

response = requests.request("POST", url, files={'file': open(path_to_your_file,'rb')}, headers=headers)

print(response.json())

var path_to_your_file = "path_to_your_file"
var fs = require("fs");

var options = { method: 'POST',
  url: 'https://'+domain+'/admin/documents/'+inbox_id,
  headers:
   { 'cache-control': 'no-cache',
     authorization: 'Bearer ' + token,
     'content-type': 'multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' },
  formData:
   { file:
      { value: fs.createReadStream(path_to_your_file),
        options:
         { filename: path_to_your_file,
           contentType: null } } } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON structured like this:

{
  "id": "string",
  "original_filename": "string",
  "inbox": "inbox_id",
  "page_count": 0,
  "prediction": {
    "sections":[
    ],
    "annotations":{
    },
    "lines":{
    }
  },
  "feedback": {},
  "evaluation_data": [
    {}
  ],
  "flag_for_review": true,
  "timings": {
    "receive_time": "2019-04-24T09:43:53.791Z",
    "start_time": "2019-04-24T09:43:53.791Z",
    "done_time": "2019-04-24T09:43:53.791Z",
    "feedback_time": "2019-04-24T09:43:53.791Z",
    "processing_period": 0
  },
  "lock": {
    "value": true,
    "since": "2019-04-24T09:43:53.791Z",
    "by": "Unknown Type: null,string"
  },
  "escalate": {
    "value": true,
    "since": "2019-04-24T09:43:53.791Z",
    "by": "Unknown Type: null,string"
  },
  "files": [
    {
      "filename": 'tests/data/files/input.pdf',
      "page": 0,
      "page_count": 1,
      "filehash": '111c9e1a519b2ebf2f22eeea20e4b1805e5c0a614afa817c7940d347831e2020',
    }
  ],
  "usage_data": {
    "annotations": 13,
    "line_items": 0,
    "lines": 0,
    "pages": 1,
    "sections": 1,
    "total": 15,
  }
}

This endpoint will return structured data for the document you sent

HTTP Request

POST https://yourdomain.contract-t.fit/documents/<inbox_id>

URL Parameters

Parameter	Description
inbox_id	The ID of the inbox to which you want to post
file	The file that you want to process

Errors

The contract.fit API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your credentials are not accepted.
402	Payment Required -- Your balance is insufficient.
403	Forbidden -- You do not have the required permission.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access an invalid method.
406	Not Acceptable -- You request isn't valid.
409	Conflict -- Your request cannot be completed due to a conflict (removal of resource still in use, or creation in violation of uniqueness requirement)
413	Payload Too Large -- Number of pages or size exceeds limit
415	Unsupported Media -- We do not support the media type of the file sent, or of embedded files (e.g., zip, email)
422	Unprocessable Entity -- We cannot process the request (corrupt or encrypted input, or
429	Too Many Requests -- The server is experiencing too heavy load, please try again in 1 minute.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.