Authentication

The Crewsum customer API authenticates every request with an API key. If you do not have a key yet, see Create an API Key.

Base URL

Send all requests over HTTPS to:

https://api.crewsum.com

Every endpoint path starts with /v1, for example https://api.crewsum.com/v1/clients/clients. The endpoint pages in the API Reference give the full path of each endpoint.

Send your API key

Put the full API key in the x-api-key request header:

x-api-key: <your-api-key>

curl "https://api.crewsum.com/v1/clients/clients" \
  -H "x-api-key: $CREWSUM_API_KEY"

const response = await fetch("https://api.crewsum.com/v1/clients/clients", {
  headers: { "x-api-key": process.env.CREWSUM_API_KEY },
});

import os
import requests

response = requests.get(
    "https://api.crewsum.com/v1/clients/clients",
    headers={"x-api-key": os.environ["CREWSUM_API_KEY"]},
)

Keep these rules in mind:

Use the x-api-key header. The API does not accept the key in an Authorization: Bearer header or in the query string.
Send the key exactly as Crewsum showed it, including the cs_ prefix.
Send the key on every request. The API does not use sessions or cookies.

Send JSON request bodies

For POST, PUT, and DELETE requests that have a body, send JSON and set the Content-Type header:

Content-Type: application/json

If the body is not valid JSON, or the header is set but the body is empty, the API returns 400. If you leave out the header, the API does not read the body as JSON, and the request usually fails with 500. See Errors.

What the API checks

For each request, the API checks, in this order:

The x-api-key header is present.
The key exists and is valid.
The key has the scope that the endpoint requires. See Scopes.
Your Crewsum account has an active subscription. A trial counts as active.

The key also identifies your Crewsum account. Requests work on the data of the account that created the key.