Developer API documentation

API Quickstart

After you have created an API application, check out these API Quickstarts:

Sample code for each of the quickstarts are available on Github


The Captricity API allows third party developers to programmatically interact with the Captricity data digitization engine. The Captricity API is a stateless, resource based web API with JSON serialization that allows applications to:


Term Related API Resources Definition
Batch Batch, Batches, BatchFile, BatchFiles, Submit Batch, Batch Price, Batch Readiness A batch represents a collection of files. A batch can be created in multiple ways by both the user and the system, including
  • Uploading files through the web UI
  • Email attachments (contact
  • Downloading from a third-party service (Dropbox, Box, Google Drive)
  • Directly using the API
  • Rejection of a page during processing
  • Sorting by the system
Batch File Batch, Batches, BatchFile, BatchFiles, Batch File Download A batch file contains metadata for each file in the batch. A file can be one of the following formats: jpg, png, gif, pdf, tiff.
Job Job, Jobs, Deep Job, Job Readiness, Job Price, Submit Job, Job Results Csv A job links all of the information needed to digitize a set of completed forms. A job ties together:
  • A blank template form (document) with 1 or more blank template pages (sheets)
  • One or more completed forms (instance sets), each of which contains a completed form page (instance) for every blank template page (sheet)
  • The digitization results after a job has been processed
Document Document, Documents, Deep Document A document is a blank template form. A document consists of one or more blank template pages (sheets). A user marks up the document using the Captricity web-based document definition tool to specify the information they want digitized.
Sheet Sheet Image, Sheet Thumbnail A sheet is a single blank template page belonging to a document that the user marks up to specify the information that they want to digitize. The user defines the data of interest by drawing template fields using the Captricity web-based document definition tool.
Instance Set Instance Set, Instance Sets, Instance Set Instances, Instance Set Shreds An instance set is one completed form. Each instance set contains at most one completed form page (instance) for each template page (sheet) in the template form (document). A complete instance set has the same number of completed form pages (instances) as its blank template form (document) has blank template pages (sheets).
Instance Instance, Instance Aligned Image An instance is a single completed form page. Each instance belongs to an instance set and corresponds to a particular blank template page (sheet).
Shred Shred, Instance Set Shreds, Shred Image, Shred Thumbnail A shred is a subregion of a completed form page (instance). A shred represents one semantic piece of data. For example, assume you are digitizing a survey and one question is the respondent's age. For each respondent you will digitize a completed form (instance set). For each completed form there will be one shred corresponding to the subregion where the respondent wrote down their age. The user defines the characteristics of a shred by drawing template fields using the Captricity web-based document definition tool.

Authorization and Authentication

The Captricity API enables a third party application to perform actions on behalf of a Captricity user. A user must specifically authorize an application before it is allowed to modify resources on their behalf. This authorization can be revoked at any time by the user.

Requests are authenticated using a signature scheme based on a secret key that is shared between the third party application developer and Captricity. Create an application here to obtain a secret key.

Example Application

The third party web site,, wants to integrate their service with Captricity by providing a list of their user's Captricity jobs. The application will then allow their users to transfer transcribed results from Captricity into an online customer relationship management tool.

Application setup

First a developer at signs up for a Captricity account and creates a new third party application. They will be given a unique application ID and a unique secret key for signing requests.

Protect your secret key. If others discover your secret key, they will be able to make requests that appear to be from your application. This can result in your application's access to the Captricity API being disabled.

Account access request

New! Check out the Account access request quickstart.

To gain access to a user's Captricity account, the application will provide the user with a link to and pass the following url-encoded GET parameters:

The return URL and third party ID parameters are used in combination with the application's secret key to create the signature parameter (details below).

When the request arrives, Captricity will authenticate the request by checking the signature. Requests with invalid signatures will be refused. If the signature is valid, the user will then have the choice to grant or deny access to the application.

User grants access

If the user chooses to grant access to the application, the user's browser is redirected to the return URL provided in the access request appended with the following url-encoded GET parameters:

The signature parameter is generated as defined below.

The application can check the signature to ensure the response is from Captricity. The application can then save the token string to allow it to access the user's Captricity resources.

User denies access

If the user chooses to deny access to the application, the user's browser is redirected to the return URL provided by the access request with the following parameters:

Mobile Applications

If the application is available for mobile devices, the application may want to register itself as a handler for URLs with a unique schema. Our application might register itself as a handler for exampledotcom:// schemas. This allows redirection back into the application once the Captricity user has allowed or denied the account access request.


To sign a request, the client will generate a hex digest of the SHA-256 hash of a parameter string created as follows:

First, serialize the alphanumerically sorted and url encoded key:value pairs. Usually a captricity client will sign URL parameters like "return-url" or "third-party-id" but for the sake of clarity we'll use these example key:value pairs:

Serialized, sorted, and URL encoded, these parameters look like this:


The signature is generated by running the SHA-256 algorithm on the serialized parameters joined to the secret key as follows:


Note the ':' between the secret key and the serialized parameters.

To continue our example, if the secret key is the string "abc123" then the signature would be the hexdigest of the SHA-256 hash of this string:


And the hash is this:


Now we can generate the final request URL:

Here is example python code for generating the signature (available in the Captricity API Python Client):

    from urllib import urlencode
    from hashlib import sha256

    def generate_signature(parameters, secret_key):
        # pull out the parameter keys
        keys = parameters.keys()

        # alphanumerically sort the keys in place

        # create an array of url encoded key:value pairs
        encoded_pairs = [urlencode({key:parameters[key]}) for key in keys] 

        # create the serialized parameters in a single, URL style string
        serialized_parameters = '&'.join(encoded_pairs)

        # create the string with the secret key and the parameters which will be hashed
        string_to_hash = '%s:%s' % (secret_key, serialized_parameters)

        # return the hex digest of the hashed string
        return sha256(string_to_hash).hexdigest()

Performing actions on behalf of a Captricity User

Once a Captricity user has granted your application access to their account, your application will be able to perform actions on behalf of the user by manipulating API resources using standard HTTP GETs, PUTs, POSTs, and DELETEs.

To succesfully make a request to a Captricity API resource, your request must include the Captricity-API-Token HTTP header.

For example:

    h = httplib.HTTP('')
    h.putrequest('GET', '/api/v1/job/')
    h.putheader('Accept', 'application/json')
    h.putheader('User-Agent', 'Your Client Name V0.1')
    h.putheader('Captricity-API-Token', 'Your Client Token')
    errcode, errmsg, headers = h.getreply()
    if errcode != 200:
        raise IOError('Response from %s was %s' % (url, errcode))
    result = json.loads(

The value for the Captricity-API-Token header is the API token you receive in the callback after the Captricity user authorizes your application. You can see your account's API tokens on the developer dashboard.


Example Usage

Here's a quick example of using our API to list the the jobs your own in your Captricity account.

Log in and then navigate to /api/v1/job/ .

This will perform a HTTP GET to the Jobs API resource. You should see a JSON list like this:

            "status": "completed",
            "user_id": 3,
            "name": "Example Job - School Survey",
            "created": "2012-10-15T16:35:19.133",
            "started": "2012-10-15T16:35:19.064",
            "sheet_count": 2,
            "modified": "2012-10-15T16:35:19.133",
            "is_example": true,
            "finished": "2012-10-15T16:35:19.063",
            "percent_completed": 100,
            "thumbnail_sheet_id": 9,
            "instance_set_count": 20,
            "id": 5,
            "document_id": 5
        *... snip! ...*

Libraries and Example Apps

We have a number of example apps and libraries available for use with the Captricity API:

Captricity Python Client

The Captricity Python Client provides a pythonic interface to the Captricity API. The Captricity Python Client is open-source and licensed under an MIT license.

Captricity API Quickstart

The Captricity API Quickstart provides example code using our python and javascript client libraries. In addition, we have a sample live site that makes use of all the examples in our javascript api quickstart.


Getting Help

Still have questions? Send us a note at


API Reference

Our API Reference is available here top