REST API and API keys

The Sessional REST API gives you read access to your core data — sessions, invoices, expenses, and profile — so you can build custom integrations, generate reports in external tools, or feed data into your own workflows.

Common use cases include:

• Pulling invoice data into a custom spreadsheet or dashboard
• Syncing session history with a personal calendar or timesheet tool
• Feeding expense data into bookkeeping software that is not natively supported
• Automating monthly reports for your accountant

To create a new API key:

1. Navigate to API settings — open the API page from your dashboard sidebar.
2. Click “Create API key” — give your key a descriptive name (e.g. “Spreadsheet sync” or “Accountant export”) so you can identify it later.
3. Copy your key — the full key is shown once at creation time. It will not be displayed again. Copy it immediately and store it securely.

API keys use the prefix sk_live_ followed by a random string. The prefix makes it easy to identify Sessional keys in your configuration files or environment variables.

All API requests must include your key in the Authorization header using the Bearer scheme:

GET /api/v1/sessions HTTP/1.1
Host: sessional.co.uk
Authorization: Bearer sk_live_your_key_here

Requests without a valid key, or with an expired or revoked key, receive a 401 Unauthorized response. The response body includes a JSON error message explaining the reason.

To protect the platform and ensure fair usage, the API enforces a rate limit of 100 requests per minute per user. This is a sliding window — each request is counted against the previous 60 seconds.

If you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

For most integrations, 100 requests per minute is more than sufficient. If you are syncing data periodically (e.g. once per hour), you are unlikely to approach the limit. If you are building a real-time dashboard, consider caching responses locally.

The API currently provides four endpoints, all returning JSON:

• GET /api/v1/sessions— list your bookings with filters for date range, status, and organisation. Returns session date, hours, rate, organisation name, status, and invoice reference if invoiced.
• GET /api/v1/invoices— list your invoices with filters for status (draft, issued, paid, overdue, void) and date range. Returns invoice number, amount, organisation, issue date, due date, status, and payment date if paid.
• GET /api/v1/expenses— list your expenses with filters for category and date range. Returns date, category, description, amount, and whether a receipt is attached.
• GET /api/v1/profile— retrieve your profile information including name, profession, registration number, specialties, and contact details.

All list endpoints support pagination via page and limit query parameters. The default page size is 50, with a maximum of 100.

The API documentation page at Dashboard > APIincludes an interactive “try it out” feature. Select an endpoint, fill in optional parameters, and click “Send” to see the live response from your account. This is the fastest way to understand the response format and test your queries before writing code.

The documentation also shows the full JSON schema for each endpoint’s response, including all available filter parameters.

If you no longer need a key, or if it may have been exposed, revoke it from the API settings page. Click the revoke button next to the key you want to disable. Revocation is immediate — any requests using that key will start returning 401 Unauthorized straight away.

You can create a new key at any time to replace a revoked one. There is no limit on the number of keys you can create, though we recommend keeping only active keys and revoking those you no longer use.