Getting started
This page shows you how to get API access for your firm, create an API key and make your first call.
What can I do with the API?
Section titled “What can I do with the API?”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.
Step 1. Ask for API access for your firm
Section titled “Step 1. Ask for API access for your firm”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.
Step 2. Create an API key
Section titled “Step 2. Create an API key”You create an API key yourself, in the SuperDocs portal, in your settings.
- Sign in to the SuperDocs portal.
- Open your settings, and find the API keys screen.
- Create a key, and choose how long it lasts.
- 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.
Step 3. Make your first call
Section titled “Step 3. Make your first call”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:
curl \ -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \ https://api.example.com/v1/pingOn Windows, in PowerShell: type curl.exe, not curl. In PowerShell, curl is a different command. Put the whole command on one line:
curl.exe -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" https://api.example.com/v1/pingThe 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.
What comes back?
Section titled “What comes back?”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.
The first call in Python or JavaScript
Section titled “The first call in Python or JavaScript”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 jsonimport osimport 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
/v1at 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 examplenextCursor. - 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.
Where to go next
Section titled “Where to go next”- 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.