Skip to content
Draft. The API described here is not released yet, and nothing on this site has been tested against it. Details may change.

Getting started

This page shows you how to get API access for your firm, create an API key and make your first call.

The SuperDocs customer API lets your own programs read your firm’s data in SuperDocs. A program sends a request over HTTPS. The API answers in JSON.

The first version of the API only reads data. It does not change anything. It is planned to read:

  • the cases you can see,
  • the documents in a case,
  • the people on a case.

The API reference lists the planned endpoints.

API access is off for every firm at the start. SuperDocs support must switch it on for your firm. Until then, nobody in your firm can create an API key. If your firm’s API access is switched off later, every request answers 403.

You create an API key yourself, in the SuperDocs portal, in your settings.

  1. Sign in to the SuperDocs portal.
  2. Open your settings, and find the API keys screen.
  3. Create a key, and choose how long it lasts.
  4. Copy the key and store it somewhere safe, for example a password manager.

The key is shown only once. SuperDocs cannot show it to you again. If you lose it, revoke it and create a new one.

Only users of a firm can create a key. A client of a firm cannot.

API keys explains how keys work, how long they last and how to keep them safe.

Your first call is GET /v1/ping. It answers the question “Is my key working?”. It tells you which firm and which user your key belongs to. It does not read any case data.

Send it with curl. Put your own key in place of the example key:

Terminal window
curl \
-H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \
https://api.example.com/v1/ping

On Windows, in PowerShell: type curl.exe, not curl. In PowerShell, curl is a different command. Put the whole command on one line:

Terminal window
curl.exe -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" https://api.example.com/v1/ping

The address https://api.example.com is a placeholder. The real address of the API is not decided yet. Every example on this site uses the placeholder. Replace it with the real address when it is published.

If your key works, the API answers with status 200 and a JSON body. The body names the firm and the user that the key belongs to, and nothing else.

If the call does not work, look at the status:

Status What it means What to do
401 The API did not accept your key. Check that you copied the whole key, and that you sent it in the header. The key may also be revoked or expired.
403 Your firm’s API access is off. Ask SuperDocs support to switch it on (step 1).
429 You sent too many requests. Wait, then try again. See Rate limits.

Errors lists every error.

These examples use only what comes with the language, so you do not need to install anything. They read the key from an environment variable called SUPERDOCS_API_KEY, so the key is not written in the code.

Python 3:

import json
import os
import urllib.request
api_key = os.environ["SUPERDOCS_API_KEY"]
request = urllib.request.Request(
"https://api.example.com/v1/ping",
headers={"Authorization": "Bearer " + api_key},
)
with urllib.request.urlopen(request) as response:
print(json.load(response))

JavaScript (Node.js 18 or later). Save it as ping.mjs and run node ping.mjs:

const apiKey = process.env.SUPERDOCS_API_KEY;
const response = await fetch("https://api.example.com/v1/ping", {
headers: { Authorization: `Bearer ${apiKey}` },
});
console.log(response.status, await response.json());

What rules do all requests and responses follow?

Section titled “What rules do all requests and responses follow?”
  • Addresses start with the version. Every address starts with /v1.
  • New fields are not a new version. SuperDocs can add a field or an endpoint to /v1 at any time. Your code should ignore fields it does not know.
  • A new version is needed to remove or change a field. Removing a field, renaming it, or changing its type or meaning needs a new version, such as /v2.
  • JSON is UTF-8. Field names are camelCase, for example nextCursor.
  • Ids are strings. Do not treat an id as a number, even if it looks like one.
  • A field with no value is null. It is still in the response. A field that is missing is not part of this version.
  • A single item comes in data: { "data": { ... } }.
  • A list comes in data, with a cursor for the next page. See Paging.
  • API keys: how keys work, and how to keep them safe.
  • Errors: what an error looks like, and what each code means.
  • Paging: how to read a long list.
  • Dates and times: how the API writes dates.
  • Rate limits: how many requests you can send.