Getting Started

We recommend downloading the Swagger docs directly from our sandbox environment for the latest, most concise documentation.

Public and private API keys

Caplinked will send you an email with your API public and private keys upon account approval. The private (secret) will be used to sign your API requests to the Caplinked API and should be kept privately (i.e. not committed to your source repository). You will be able to reset/roll your private key as needed. The public key will be used to identify your Caplinked API account.

User Tokens

The user token is used to identify the user resource in your organization. All API requests should specificy this header.

Signing your request

You will need to sign your requests with your private key via the HmacSHA256 algorithm. Below is an example done in javascript:

var api_key = 'f15fbbd103f66b2e472316857cc37f8378axxxxx';
var api_user_token = 'cd3361c8b8c4a914afbf587c701128bf016xxxxx';
var api_secret_key = '7c1c971ad1f1170b6c984023fc22bcaa0dd21e510bf70772e55867235f7xxxxx';

// utc expiration date
var api_exp_date = Math.floor(Date.now() / 1000) + 300;

var payload = api_key + api_user_token + api_exp_date;

var hash = CryptoJS.HmacSHA256(payload, api_secret_key);
var signature = "Method=HMAC-SHA256 Signature=" + hash;

var headers = {
'x-api-key': api_key,
'x-api-user-token': api_user_token,
'x-api-signature': signature,
'x-api-exp-date': api_exp_date,
}

// curl request example
curl https://sandbox.caplinked.com/api/v1/users/me \
-H "x-api-key: f15fbbd103f66b2e472316857cc37f8378axxxxx" \
-H "x-api-user-token: cd3361c8b8c4a914afbf587c701128bf016xxxxx" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=bb472a31cb557208028c1aab0a159d362fc1efebc23623d81bd05f575d3da9b8" \
-H "x-api-exp-date: 1487628036" \
-X GET


Example

Once you’ve received your CapLinked API key, you can upload and view a file in less than 2 minutes. Follow these commands to get started:

Create your first team

Teams are a way to group users and workspaces.

curl https://sandbox.caplinked.com/api/v1/teams \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"team": {"name": "New Team" }}' \
-X POST

Create your first workspace

Workspaces are where files are stored, users are granted access, and activity it recorded.

curl https://sandbox.caplinked.com/api/v1/workspaces \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"workspace": { "name": "New Workspace"}, "team_id": 1 }' \
-X POST

Create a folder

Folders store other folders and files.

curl https://sandbox.caplinked.com/api/v1/folders \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"name": "New Folder", "workspace_id":1 }' \
-X POST

Upload a file

curl https://sandbox.caplinked.com/api/v1/files/upload \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"workspace_id":1, "folder_id":1, "file_name": "NEW_FILE" }' \
--data-binary "@NEW_FILE" \
-X PUT

Get file information

curl https://sandbox.caplinked.com/api/v1/files/1?workspace_id=1 \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-X GET


Next Steps

There’s so much more you can do with the CapLinked API. Visit the full documentation for an exhaustive list. Here are just a few examples:

Create a group

Groups are where users gain access to folder and files inside a workspace.

curl https://sandbox.caplinked.com/api/v1/groups \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"group": {"name": "New Group", "workspace_id":1, "file_managing_abilities": true }}' \
-X POST

Configure permissions for your group

The permissions endpoint are where you decide which files a group can access, and what types of access they have.

curl https://sandbox.caplinked.com/api/v1/permissions/folders/1 \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"group_id": 1, "workspace_id": 1, "verb": "set", "folder_action": "download"}' \
-X PUT

Enable watermarking for your group

Custom watermarks are applied to documents in the viewer and upon download. Dynamic watermarks may include crucial user information, such as name, time stamps, email, and IP address.

curl https://sandbox.caplinked.com/api/v1/groups/1/watermarking \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"group": {"watermarking": true }}' \
-X PUT

Create a non-admin user

This user represents the person viewing documents. You will receive a token to make requests on their behalf. Store this user_token so all requests made with it are tied to that user.

curl https://sandbox.caplinked.com/api/v1/users \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-d '{"user": {"email": "email@example.com", "first_name": "user_first_name", "last_name": "user_last_name", "time_zone": "UTC" }}' \
-X POST

Add user to the group

Give permission to a user for viewing folders and files. Use the group id created before in the url.

curl https://sandbox.caplinked.com/api/v1/groups/:group_id/memberships?user_id=:user_id&send_email=false \
-H "x-api-key: YOUR PUBLIC API KEY" \
-H "x-api-user-token: USER_TOKEN" \
-H "x-api-signature: Method=HMAC-SHA256 Signature=GENERATED_SIGNATURE" \
-H "x-api-exp-date: UNIX_UTC_TIMESTAMP_EXPIRATION" \
-X POST

Note: Use the non-admin user token to request downloads or view files with watermarking enabled.