The Captricity API is designed to enable 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.

You must register your application to obtain this 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 will contact to register their third party application. They will be given a unique ID string for the third party application 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

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:
  • A Return URL (key: return-url)
  • Their third party ID (key: third-party-id)
  • Signature (key: signature)
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:
  • Request granted (key: request-granted, value: true)
  • API token string for the user's Captricity account (key: token)
  • Signature (key: signature)
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:
  • Request denied (key: request-denied, value: true)
  • A nonce (key: nonce)
  • Signature (key: signature)

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:

  • apple:23
  • moonUnit:California & Rocks
  • flower-power:still lives
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:
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()

Stay up to date!

Learn how data access is driving the big data revolution and business strategy at the world’s leading organizations.

Sign up to receive our updates on the newest technology and trends in big data and analytics.

Your privacy is important to us—we will never sell or share your email address!